OAuth 2.0

OAuth 2.0 is a protocol that lets external apps request authorization to private details in a user’s 4me account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

Before getting started, developers need to register their application in the Applications console of their My Profile section. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

Authorization Code Flow

OAuth Authorization Code flow

The image above illustrates the following 10 steps that complete an OAuth Authorization Code flow from 3rd party applications:

  1. A user clicks on a login or authorization link within the third-party application. The third-party application now needs to retrieve data that the user is allowed to access in 4me.

  2. The third-party application redirects the user to perform an authorization request against the /oauth/authorize endpoint of 4me to retrieve an authorization code. At this point, the application passes the following information to 4me:

    • the client ID of the application record in 4me
    • the redirect URI - this is the web address to which the user is sent after access is granted.

  3. 4me checks if the user has previously authorized the third-party application to access 4me.

    If authorization was already provided, the flow continues with step 5.

    If not, 4me will show the user an authorization prompt.

  4. The authorization prompt asks the user to either ‘Deny’ or ‘Allow’ the third-party application access to 4me.

    If the user denies, the flow ends.

    If the user allows access, this authorization is registered in 4me.

  5. 4me generates an authorization code and returns this code to the third-party application as part of the redirect URL.

  6. The third-party application performs an access token request against 4me’s /oauth/token endpoint to request an access token and a refresh token. The following data is provided by the application:

    • the client ID of the application record in 4me,
    • the client secret of the application record in 4me,
    • the authorization code the application received from 4me in step 5, and
    • the redirect URI that was provided in step 2.

  7. 4me then generates a temporary access token and a refresh token.

    The access token allows the third-party application to retrieve data from 4me on behalf of the user. An access token is valid only for 1 hour.

    The refresh token allows the third-party application to retrieve a new access token and refresh token when the access token expires (see refresh token request. A refresh token is valid for 2 weeks.

    4me returns these two tokens to the third-party application.

  8. The third-party application uses the tokens to make 4me API requests.

  9. 4me returns API responses to the third-party application.

  10. The third-party application uses the data received in the API responses to render a page for the user or perform a background action.

It is important to point out that after a user has permitted a third-party application access to 4me in step 4, the user is able to see this in the ‘Access & Security’ section when the user opens ‘My Profile’ in 4me.

Authorized Applications in the Access & Security section of My Profile

This is also where users can revoke the permissions they provided to third-party applications. When a user revokes the authorization from an application, the access tokens that the application obtained from 4me for the user immediately stop working.

Authorization request

GET /oauth/authorize

Parameters

client_id
Required string - The client ID that belongs to the application registered in 4me.
response_type
Required string - Must be set to code.
redirect_uri
Required string - URL in the application where users will be sent after authorization. The redirect URL must match one of the endpoints of the application registered in 4me.

Access Token request

POST /oauth/token

Parameters

client_id
Required string - The client ID that belongs to the application record registered in 4me.
client_secret
Required string - The client secret you received from 4me when you registered.
redirect_uri
Required string - Must match the redirect URL that was used in the Authorization request.
code
Required string - The authorization code you received in the redirect after the user authorizes the 3rd party application.
grant_type
Required string - Must be set to authorization_code.

Response

access_token
Required string - Temporary OAuth access token. Allows the 3rd party application to retrieve data from 4me on behalf of the user.
The token becomes expires after 1 hour. The refresh token can be used to generate a new access token. The token becomes invalid when:
  • when the user revokes the authorization. The user will have to re-authorize the application.
  • when the scopes of the application is changed. The user will have to re-authorize the application.
  • when the application is disabled or deleted.
refresh_token
Required string - OAuth refresh token. Allows the 3rd party application to retrieve a new access token (and refresh token) when the access token expires.
The refresh token becomes expires after 2 weeks. The token becomes invalid for the same reasons as listed with the access_token.

Refresh Token request

POST /oauth/token

Parameters

client_id
Required string - The client ID that belongs to the application record registered in 4me.
client_secret
Required string - The client secret you received from 4me when you registered.
refresh_token
Required string - The refresh token you received from the Access Token request or a previous Refresh Token request.
grant_type
Required string - Must be set to refresh_token.

Response

access_token
Required string - Temporary OAuth access token. Allows the 3rd party application to retrieve data from 4me on behalf of the user.
The token becomes expires after 1 hour. The refresh token can be used to generate a new access token. The token becomes invalid when:
  • when the user revokes the authorization. The user will have to re-authorize the application.
  • when the scopes of the application is changed. The user will have to re-authorize the application.
  • when the application is disabled or deleted.
refresh_token
Required string - OAuth refresh token. Allows the 3rd party application to retrieve a new access token (and refresh token) when the access token expires.
The refresh token becomes expires after 2 weeks. The token becomes invalid for the same reasons as listed with the access_token.