Authenticating with OAuth

Documentation
Authenticating with OAuth

What is OAuth?

OAuth is an open standard for authorization. It allows applications, such as our Fourth platform, to provide clients with secure access using a token system.

There are two versions of OAuth – 1.0 and 2.0 – that are not backwards compatible. At Fourth, we have implemented OAuth 2.0 on several of our REST APIs (with the other REST APIs using Basic authentication). So, when you see OAuth discussed on this site, we are refering to OAuth 2.0 only.

Participants and workflow

There are three participants that take part in a Fourth OAuth interaction:

Client — your application
Server — the Fourth service you want to access
OAuth service — the Fourth OAuth service

The workflow between these participants is:

Workflow for OAuth requests, as described below

The client sends a request to the OAuth service. This request includes a client ID, client secret (password), and the desired scope (discussed below):
   grant_type=client_credentials
   &client_id=acme
   &client_secret=acmeExamplePassword
   &scope=NotificationService
For successful requests, the OAuth service sends back a token. For example:
   "access_token": "eyJhbGciOiJS…",
   "expires_in": 3600,
   "token_type": "Bearer",
   "refresh_token":"IwOGYzYTlmM2Y...",
   "scope": "NotificationService"
The client sends this token to the server as part of their API request in the request header. This uses the Authorization: Bearer header:
Authorization: Bearer eyJhbGciOiJS…
The client continues to use the token until the token’s timeout is reached.
The client requests a new token, and the process repeats.

Scopes

When you make an OAuth request, you need to specify the scope. This defines the service (e.g. the API access) that you are requesting. For example, when using the Notifications API, your OAuth request must specify the scope NotificationService. This tells the OAuth service that you want access to the Notification API’s services. The OAuth service will confirm that the specified client or user is allowed access to the requested service, and then provide a token which has this permission.

For Fourth APIs that use OAuth, you can find the scope on its reference page under the Authentication heading.

Grant types

You can use these grant types when you first request an access token:

client_credentials — this indicates that the credentials you are using are for your application.
password — this indicates that the credentials are those of a Fourth end user. Only use this grant type if you are using a workflow where an end user provides their authentication details.

For almost all use cases for our API, we would expect the client to send in client_credentials. These requests include the authentication details as client_id and client_secret:

grant_type=client_credentials
&client_id=acme
&client_secret=acmeExamplePassword
&scope=NotificationService

Password grant types must include the client’s secret — if one was issued — as well as the authentication details for the end user. For example:

grant_type=password
&username=user@example.com
&password=usersExamplePassword
&client_id=acme
&client_secret=acmeExamplePassword

Token format

The valid characters in a bearer token are alphanumeric, and the following punctuation characters: -._~+/

Timeouts and refresh tokens

Access tokens have a timeout period, after which you can’t use them anymore. In the response from the OAuth service, this timeout is shown in the "expires_in" field. The value is in seconds; for example, 3600 is one hour.

As you reach the timeout, you can do one of two things:
• Preemptively request a new token.
• Wait for the token to expire and then request a new token.

How you request a new token also depends on whether you received a refresh token in the original response. If you did not receive a refresh token, then you make the same client_credentials (or password) request as before. However, if you received a refresh token, then you can optionally use a grant type of refresh_token; for example:

grant_type=refresh_token
&refresh_token=IwOGYzYTlmM2Y...

Note that if you are using a refresh token for an end user (grant type password), you will need to include the client's credentials:

grant_type=refresh_token
&refresh_token=IwOGYzYTlmM2Y...
&client_id=acme
&client_secret=acmeExamplePassword

Example request and response

Request

Endpoint:

POST [ROOT]/oauth/connect/token

Body:

grant_type=client_credentials
&client_id=acme
&client_secret=acmeExamplePassword
&scope=NotificationService

Response

Body:

{
   "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1MjBENkTQzMjQzN2Y3Y2UyNl07W1VTRVJfTUFOQUdFTUVOVCwgMDAxMWwwMDAwMEI1dmlmQUFCXTtbRk9VUlRIX0FDQ09VTlRfUeyJuYmYiOjE1ODYxODUyMDAsImV4cCI6MTU4NjE4ODgwMCwiaXNzIjoiaHR0cHM6Ly9hcGktZGV2LmZvdXJ0aC5jDRSwgRkFTXzEyOF0iLCJzY29wZSI6WyJtZW51c2VydmljZS1wb3NfcmVhZCJdfQ.ROEVIdIF8aCL4Ku4k7nGSXp4sG7xrHkG8j1XzGlz0JlU9h2Q4qsh8Yz1euMXMcXu4kDetGhqzVO9ULeOFLo5Sjz0VSVklDRSwgRkFTXzEyOF0iLCJzY29wZSI6WyJtZW51c2VydmljZS1wb3NfcmVhZCJdfQ.ROEVIdIF8aCL4Ku4k7nGSXp4sGQSfas8UAoYCnTZacsZXNmb3JjZUFjY291bnRJZCI6IjAwMTFsMDAwMDBCNXZpZkFBQiIsImNsaWVudF9zb3VyY2VTeXN0ZW1NYXBwaW5ncyI6IltTVEFSQ0hFRiwgMDAxMb20vdWF0L29hdXRoIiwiYXVkIjpbImh0dHBzOi8vYXBpLWRldi5mb3VydGguY29tL3VhdC9vYXV0aC9yZXNvdXJjZXMiLCJtZW51c2VydmljZS1wb3NfcmVhZCJdLCJjbGllbnRfaWQiOiJTb2RleG9PbW5pY28iLCJjbGllbnRfc2FtTVEFSQ0hFRiwgMDAxMWwwMDAwMEI1dmlmQUFCXTtbUjksIDAxMzlmNjI3LThjOTUtNGM0Mi1hYjQ2LM0Mi1hYjQ2LTQzMjQzN2Y3Y2UyNl07W1VTRVJfTUFOQUdFTUVOVCwgMDAxMWwwMDAwMEI1dmlmQUFCXTtbRk9VUlRIX0FDQ09VTlRfU0VSVklWwwMDAwMEI1dmlmQUFCXTtbUjksIDAxMzlmNjI3LThjOTUtNGQ3RDBGNUE5QkE5OUFDRjY4RTFBMUZGOEUwN0Q5QkYzN0IiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwU0RXMTlEMXFicVpyUGFPR2hfNDRIMmI4M3MifQUxn0b1qcXjSmfiWDgjJows5zUAVTzUX773fm2UqZefl040NX4NnmfyOleeQzzChoaY1bVJRF2UdDUm2DNPxiMP83RBFR6X35mxyBCYzNh7KIv2a9KoQxA_wx83rXaZlJSQlgxvCNZc18lfS_rSVAB-X_gpMVNDrEh-fSRH8wd6ep7pPvhMJQj6IX00qXdTWYUO-6jUIFdSP5pHZ7k1FF4L8lGW1QGJhODA",
   "expires_in": 3600,
   "token_type": "Bearer",
   "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk...",
   "scope": "NotificationService"
}

Troubleshooting

If there is a problem with your request, then we will return an HTTP 400 Bad Request status code. The request body will include an error message; for example:

{
   "error": "invalid_request",
   "error_description": INVALID_LOGIN: Invalid username, password, securty token; or user locked out."
}

error is always returned, and holds the standard OAuth name for the error.
error_description is not always returned, and the text may be updated by Fourth in the future. Note that it is not intended for end users to see.

The standard errors we return are:

invalid_request — The request doesn't include all the required parameters. This may also be returned if the request includes any unsupported or repeated parameters.
invalid_client — Either (or both of) the client_id or client_secret is incorrect.
invalid_scope — The OAuth server doesn't recognise the scope sent in. Please check the spelling and format. Scopes are case-sensitive.
unauthorized_client — The client does not have access to the specified grant type. If you need access extended to another API, please contact Fourth.
unsupported_grant_type — The OAuth server doesn't recognise the grant type sent in. Please check the spelling and format. Grant types are case-sensitive.