Authorization

Clients making calls to the API on behalf of a user require an access token which can be acquired via the following (simplified) OAuth 2.0 flow.

  1. Register the client via POST /oauth/v1/register and record the client configuration contained in the response. These client configuration values should be kept secure.
  2. Redirect the user’s browser to GET /oauth/v1/auth with the required client configuration values in the query parameters, including a redirect_uri. If the user grants the authorization to the client, the user’s browser will be redirected to the redirect_uri with an authorization code.
  3. Request POST /oauth/v1/token with the authorization code plus other client configuration values and record the access token and refresh token contained in the response.
  4. Refresh the access token if it expires or otherwise becomes invalid using the refresh token.

Client Registration

Clients register with the API using an open registration lifecycle.

Most client registration and configuration endpoints (POST /oauth/v1/register, GET /oauth/v1/clients/(client_id), and PUT /oauth/v1/clients/(client_id)) return an application/json response body that is an object with the client configuration as top-level members:

Client Configuration:
 
  • client_id – The client id.
  • redirect_uris – A list of redirect URIs (strings) for use in other oauth flows. Specifically, one of these URIs must always be used whenever a redirect_uri is required.
  • scope – A space separated list of scope values that the client can use when requesting access tokens.
  • client_secret – The client secret for use in other oauth flows.
  • client_secret_expires_at – Time at which the client_secret will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
  • registration_access_token – The access token that is used at the client configuration endpoint to perform subsequent operations upon the client registration through the client configuration enpdoints (GET /oauth/v1/clients/(client_id), PUT /oauth/v1/clients/(client_id), and DELETE /oauth/v1/clients/(client_id)).
  • registration_client_uri – The fully qualified URL of the client configuration endpoint for this client. The client MUST use this URL as given when communicating with the client configuration endpoint.
  • client_name – (optional) – The human-readable name of the client to be presented to the user.
  • client_uri – (optional) – The URL of the homepage of the client.
  • logo_uri – (optional) – The URL that references a logo for the client.
POST /oauth/v1/register
JSON Parameters:
 
  • redirect_uris (string_array) – An array of redirect URIs for use in other oauth flows.
  • client_id (string) – (optional) – A requested client id. If a client is already registered with the same client id, a unique client id based on the requested one will be created instead. If this parameter is omitted, a completely random client id will be created.
  • client_name (string) – (optional) – The human-readable name of the client to be presented to the user.
  • client_uri (string) – (optional) – The URL of the homepage of the client.
  • logo_uri (string) – (optional) – The URL that references a logo for the client.
  • scope (string) – (optional) – A space separated list of scope values that the client can use when requesting access tokens. Currently, the only valid value is "data".
Status Codes:
  • 201 Created – Successfully created a new client. The application/json response body will be an object with the client configuration as top-level members.
  • 400 Bad Request

    The application/json response body will be an object with the error information as top-level members:

    Response Data:
    • error – The error. Possible values are invalid_request and server_error.

Example request:

POST /oauth/v1/register HTTP/1.1
{
  "redirect_uris": ["http://example.com/callback"],
  "client_id": "my_example_app",
  "client_name": "My Example Application",
  "client_uri": "http://example.com",
  "logo_uri": "http://example.com/logo.png",
  "scope": "data"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "client_id": "my_example_app",
  "redirect_uris": ["http://example.com/callback"],
  "scope": "data",
  "client_secret": "bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au",
  "client_secret_expires_at": 0,
  "registration_access_token": "VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE",
  "registration_client_uri": "https://my-coal.org/oauth/v1/clients/my_example_app",
  "client_name": "My Example Application",
  "client_uri": "http://example.com",
  "logo_uri": "http://example.com/logo.png"
}

Client Configuration

The client configuration endpoint is a protected resource that is provisioned by the server to facilitate viewing, updating, and deleting a client’s registered information. If a client ever forgets its client configuration values, they can be retreived via GET /oauth/v1/clients/(client_id) as long as the client knows its registration_client_uri and registration_access_token.

The location of this endpoint is communicated to the client through the registration_client_uri member of the POST /oauth/v1/register response. Authorization for this endpoint requires that the client’s registration_access_token be set in the request Authorization header field using the “Bearer” scheme as specified in RFC6750: Authorization Request Header Field.

GET /oauth/v1/clients/(client_id)

Read the current configuration of the client (client_id).

Request Headers:
 
Response Headers:
 
Status Codes:
  • 200 OK – Successfully returned the client configuration. The application/json response body will be an object with the client configuration as top-level members. Some of these values, including the client_secret, client_secret_expires_at, and registration_access_token, may be different from those in the initial POST /oauth/v1/register response. If there is a new client secret and/or registration access token in the response, the client must immediately discard its previous client secret and/or registration access token. The value of the client_id will not change from the initial POST /oauth/v1/register response.
  • 401 Unauthorized – Invalid or no Authorization request header provided. The WWW-Authenticate response header will contain the error.

Example request:

GET /oauth/v1/clients/my_example_app HTTP/1.1
Authorization: Bearer VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "client_id": "my_example_app",
  "redirect_uris": ["http://example.com/callback"],
  "scope": "data",
  "client_secret": "bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au",
  "client_secret_expires_at": 0,
  "registration_access_token": "VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE",
  "registration_client_uri": "https://my-coal.org/oauth/v1/clients/my_example_app",
  "client_name": "My Example Application",
  "client_uri": "http://example.com",
  "logo_uri": "http://example.com/logo.png"
}
PUT /oauth/v1/clients/(client_id)

Update the configuration of the client (client_id).

Request Headers:
 
Response Headers:
 
JSON Parameters:
 
  • client_id (string) – The client id. If not correct, a 400 Bad Request invalid_client_id response will result.
  • redirect_uris (string_array) – The new client redirect URIs.
  • client_secret (string) – The client secret. If this value does not match the current client secret, a 400 Bad Request invalid_request response will result.
  • scope (string) – (optional) – A space separated list of scope values. If there are new values that are not part of the current scope, a 400 Bad Request invalid_request response will result. Note that this means a client can remove scope values, but can never add them. If not present, the client scope will be unmodified.
  • client_name (string) – (optional) – The new human-readable name of the client. If not present, the client name will be set to null.
  • client_uri (string) – (optional) – The new URL of the homepage of the client. If not present, the homepage URL will be set to null.
  • logo_uri (string) – (optional) – The new URL that references a logo for the client. If not present, the logo URL will be set to null.
Status Codes:
  • 200 OK – Successfully updated the client configuration. The application/json response body will be an object with the new client configuration as top-level members. Some of these values, including the client_secret, client_secret_expires_at, and registration_access_token, may be different from those in the initial POST /oauth/v1/register response. If there is a new client secret and/or registration access token in the response, the client must immediately discard its previous client secret and/or registration access token. The value of the client_id will not change from the initial POST /oauth/v1/register response.
  • 400 Bad Request

    The application/json response body will be an object with the error information as top-level members:

    Response Data:
    • error – The error. Possible values are invalid_request, invalid_client_id, and server_error.
  • 401 Unauthorized – Invalid or no Authorization request header provided. The WWW-Authenticate response header may be set and contain the error.

Example request:

PUT /oauth/v1/clients/my_example_app HTTP/1.1
Authorization: Bearer VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE
{
  "client_id": "my_example_app",
  "redirect_uris": ["http://example.com/v2/callback"],
  "client_secret": "bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au",
  "scope": "data",
  "client_name": "My Example Application v2",
  "client_uri": "http://example.com/v2",
  "logo_uri": "http://example.com/logo_v2.png",
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "client_id": "my_example_app",
  "redirect_uris": ["http://example.com/v2/callback"],
  "scope": "data",
  "client_secret": "bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au",
  "client_secret_expires_at": 0,
  "registration_access_token": "VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE",
  "registration_client_uri": "https://my-coal.org/oauth/v1/clients/my_example_app",
  "client_name": "My Example Application v2",
  "client_uri": "http://example.com/v2",
  "logo_uri": "http://example.com/logo_v2.png"
}
DELETE /oauth/v1/clients/(client_id)

Remove the client and all grants and tokens associated with it (client_id).

Request Headers:
 
Response Headers:
 
Status Codes:
  • 204 No Content – Successfully deprovisioned the client.
  • 401 Unauthorized – Invalid or no Authorization request header provided. The WWW-Authenticate response header may be set and contain the error.

Example request:

DELETE /oauth/v1/clients/my_example_app HTTP/1.1
Authorization: Bearer VlhLNF2vifRsppohNr7gBcbcOO5khEqADalHlPYE

Example response:

HTTP/1.1 204 No Content

Authorization Code

Clients are granted a unique, one-time-use authorization code in response to an explicit, web-based authorization grant from a logged-in user.

GET /oauth/v1/auth

A user-facing web UI to prompt the user to grant or deny OAuth access for a client.

Query Parameters:
 
  • client_id – The client id to authorize.
  • redirect_uri – The fully qualified URL that the user’s browser will redirect to with the access code or error. This must be one of the URIs in the client’s configuration redirect_uris.
  • response_type – This should always be code when requesting an access code.
  • scope – The scope for the authorization code request. Must always be data.
Status Codes:
  • 302 Found – If the user grants authorization, the user’s browser will redirect to the redirect_uri with the authorization code passed via the code query parameter.
  • 302 Found – If the user denys authorization or an error occurs, the user’s browser will redirect to the redirect_uri with the error passed via the error query parameter.

Example (user browser) request:

GET /oauth/v1/auth?client_id=my_example_app&redirect_uri=http://example.com/callback&response_type=code&scope=data HTTP/1.1

Example (user browser) response:

_images/grant_auth.png

If the user grants authorization to the client, a 302 Found response is returned to the user’s browser. The Location header in the response is set to the redirect_uri with the code query parameter set to the authorization code:

HTTP/1.1 302 Found
Location: http://example.com/callback?code=YEhb6FWOcPgnTUWtHwPcgBEojQjhU619YfshnqVd

If the user denys authorization to the client, a 302 Found response is returned to the user’s browser. The Location header in the response is set to the redirect_uri with the error query parameter set:

HTTP/1.1 302 Found
Location: http://example.com/callback?error=access_denied

Access Token

Clients use an authorization code to acquire an access token and a refresh token. These tokens are unique and tied to both the client and the user that granted the authorization code. Authorization for secured Data APIs requires that a valid access token be set in the request Authorization header field using the “Bearer” scheme as specified in RFC6750: Authorization Request Header Field.

POST /oauth/v1/token

The client acquires tokens by making a request to the token endpoint, posting the following parameters in the request body using the application/x-www-form-urlencoded or application/json formats with a character encoding of UTF-8.

Form Parameters:
 
  • client_id – The client id.
  • client_secret – The current client secret.
  • grant_type – Should be authorization_code to convert an autorization code into an access token.
  • code – The authorization code.
  • redirect_uri – The fully qualified redirect URL. This must be one of the URIs in the client’s configuration redirect_uris.
  • scope – The scope for the access token. Must always be data.
Status Codes:
  • 200 OK

    Successfully converted the authorization code into access and refresh tokens. The application/json response body will be an object with the token information as top-level members:

    Response Data:
    • access_token – The access token.
    • refresh_token – The refresh token.
    • expires_in – The lifetime in seconds of the access token.
    • token_type – Will always be Bearer
  • 400 Bad Request

    The application/json response body will be an object with the error information as top-level members:

    Response Data:
    • error – The error. Possible values are:
      • invalid_request – Missing parameters.
      • unsupported_grant_type – Incorrect grant type.
      • invalid_grant – Incorrect access code or redirect URI.
      • invalid_client – Incorrect client id or client secret.
      • invalid_scope – Incorrect scope.
      • server_error – Generic server error.

Example request

POST /oauth/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=my_example_app&
client_secret=bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au&
grant_type=authorization_code&
code=YEhb6FWOcPgnTUWtHwPcgBEojQjhU619YfshnqVd&
redirect_uri=http%3A%2F%2Fexample.com%2Fcallback&
scope=data

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "wIt7U1cpa5B4Rqbbvie6Mye1sWiwAjZ7H7kAXIjK",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "PuFZ2Hyu6R6eIAxVG9Y4j4kFRYsCapISTR0n3AUM"
}

Refresh Token

When an access token expires, or otherwise becomes invalid, a one-time-use refresh token can be used to generate a new set of tokens (access and refresh).

POST /oauth/v1/token

The client acquires tokens by making a request to the token endpoint, posting the following parameters in the request body using the application/x-www-form-urlencoded or application/json formats with a character encoding of UTF-8.

Form Parameters:
 
  • client_id – The client id.
  • client_secret – The current client secret.
  • grant_type – Should be refresh_token to generate a new set of tokens.
  • refresh_token – The refresh token.
  • scope – The scope for the access token. Must always be data.
Status Codes:
  • 200 OK

    Successfully generated a new set of access and refresh tokens. The application/json response body will be an object with the token information as top-level members:

    Response Data:
    • access_token – The access token.
    • refresh_token – The refresh token.
    • expires_in – The lifetime in seconds of the access token.
    • token_type – Will always be Bearer
  • 400 Bad Request

    The application/json response body will be an object with the error information as top-level members:

    Response Data:
    • error – The error. Possible values are:
      • invalid_request – Missing parameters.
      • unsupported_grant_type – Incorrect grant type.
      • invalid_grant – Incorrect refresh token.
      • invalid_client – Incorrect client id or client secret.
      • invalid_scope – Incorrect scope.
      • server_error – Generic server error.

Example request

POST /oauth/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=my_example_app&
client_secret=bdv8HtrspbJh5F5KOlAUkDOl8KAyYcfsDQoTk1au&
grant_type=refresh_token&
refresh_token=PuFZ2Hyu6R6eIAxVG9Y4j4kFRYsCapISTR0n3AUM&
scope=data

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "vByKXlrmJzAOtD9t27B9Gf9szoA55JYBuMkvbs8f",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "9e97DujgPxnpnlr4OkYn8QSr9QdhSQXwED96BRZs"
}