Authentication

OAuth

OAuth 2.0 is the industry-standard protocol for authorization. It allows your application to authenticate with Worksome on behalf of other users.

This is the preferred way for you to interact with the Worksome API.

Creating an OAuth Client

OAuth clients can be generated can be created and managed via our API clients page.

Worksome support setting a client name, which can be used to identify your client within your list, and a redirect URL (or callback URL). The redirect URL is used to specify which URL is supported for redirection as part of the OAuth flow.

Redirect URLs ensure that Worksome will redirect the user back to the correct application, after authorisation.

As an example, if your domain was example.org, you might have the redirect URL as https://example.org/callback. Upon authorisation, the user would be redirected back to that redirect URL.

The OAuth Flow

Users are redirected to request their Worksome identity

Users should be redirected to the following URL from your application, this is usually via an authorisation link or button on your website.

GET https://auth.worksome.com/oauth/authorize

The authorisation endpoint takes the following input parameters:

Parameter name	Type	Description
`client_id`	`string`	Required. The client ID your received from Worksome when registering.
`response_type`	`string`	Required. This should be set to `code`.
`redirect_uri`	`string`	Required. The URL in your application where users will be sent after authorisation.
`state`	`string`	This is an unguessable random string. It is used to protect against cross-site request forgery (CSRF) attacks.
`prompt`	`string`	One of `consent` (the authorization approval screen will always be shown) or `login` (the user will always be prompted to log in, even if they have a session), or if excluded, the user will only be prompted for authorisation if they have not done so previously.

Users are redirected back to your site by Worksome

If the authorisation request is accepted by the user, Worksome redirects back to your site using the Redirect URL, with a temporary code, as well as the state if provided. The temporary code will expire after 10 minutes.

If the states do not match, then a third party created the request, and you should abort the process.

The code should now be exchanged for an access token. This should be done within your application’s backend, and should not be visible to the user (as it contains your client secret).

POST https://auth.worksome.com/oauth/token

The token endpoint takes the following input parameters:

Parameter name	Type	Description
`client_id`	`string`	Required. The client ID your received from Worksome when registering.
`client_secret`	`string`	Required. The client secret your received from Worksome when registering.
`code`	`string`	Required. The code you received from Worksome as part of the previous step.
`grant_type`	`string`	Required. The grant type should be `authorization_code`.
`redirect_uri`	`string`	Required. The URL in your application where users are sent after authorisation.

The data will be included as JSON in the response. For example:

{
    "token_type": "Bearer",
    "expires_in": "...",
    "access_token": "...",
    "refresh_token": "..."
}

Your application accesses the API with the user’s access token

The access token allows you to make requests to the API on a behalf of a user.
```
POST https://api.worksome.com/graphql
```
For example, in curl you can set the Authorization header like this:
```
$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.worksome.com/graphql
```

Refreshing OAuth Tokens

Your OAuth token can be refreshed by making another POST request to the token URL (/oauth/token).

This requires a grant_type of refresh_token, the refresh token (refresh_token), and your client_id and client_secret.

curl -X POST https://auth.worksome.com/oauth/token \
  -H 'Authorization: Bearer {access_token}' \
  -d 'refresh_token={refresh_token}' \
  -d 'grant_type=refresh_token' \
  -d 'client_id={client_id}' \
  -d 'client_secret={client_secret}'

Personal Access Tokens

Personal access tokens are tokens for a specific user, these allow you to generate a token without using the OAuth flow. These tokens are useful for if you are testing the API.

You can manage the personal access tokens for your account via our API tokens page.

Authenticating with the API

All API calls that require authentication must provide a standard Authorization header using the Bearer authentication scheme.

To make a test request via curl, run the command below with your token:

curl -H "Authorization: Bearer ${WORKSOME_API_TOKEN}" -X POST -d " \
 { \
   \"query\": \"query { profile { name }}\" \
 } \
" https://api.worksome.com/graphql

The string value of “query” must escape newline characters or the schema will not parse it properly. For the POST body, use outer double quotes and escaped inner double quotes.

Token expiration

By default, generated API tokens are valid for a year from creation. Upon reaching your token’s expiration date, the token is automatically revoked.

Revoking a token

Tokens can be manually revoked via the API tokens page. This is useful for when the token is no longer necessary, or for security purposes.

Revoking an OAuth client

Clients can be manually revoked via the API clients page. This will prevent the creation of new tokens with this client, and also prevent any tokens generated by this client from authenticating.