Delegated authorization ^PRERELEASE

Description #

When authenticated as an account that has granted delegated authorization through a Business Connect authorization request, a short lived code can be obtained for an account or resource that can then be exchanged for an access_token and refresh_token for the account or resource.

This can be thought of as being similar to the standard OAuth authorization flow, but it happens without any direct user involvement.

The steps are:

1. Make a Delegated Authorization request
2. Receive a code via a request made to the callback_url provided to the access request
3. Trade the code for access tokens for the account or resource by making an Access Token Request

• Note that the callback_url must be passed with the code in place of the redirect_uri

1. Use the tokens in the same way as those retrieved via the standard OAuth authorization flow

URL format #

{data_center_url}/v1/delegated_authorizations

Example request #

POST /v1/delegated_authorizations HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
    "profile_id": "{PROFILE_ID}",
    "email": "{EMAIL_OF_ACCOUNT_TO_ACCESS}",
    "callback_url": "{CALLBACK_URL}",
    "scope": "{SCOPES}",
    "state": "{STATE}"
}

Example Response #

HTTP/1.1 202 Accepted

You will not receive a direct response to your authorization request, instead the callback_url will receive a request in the future indicating success or failure.

Request parameters #

profile_id required  #

This specifies the ID of the profile you wish to get delegated authorization through.

email required  #

The email address of the account or resource to receive delegated access to.

callback_url required  #

The URL to callback with the result of the delegated access request.

See Callback examples for examples of the types of request the callback_url will receive.

scope required  #

The scope of the privileges you want the eventual access_token to grant.

These must have previously been granted via the delegated_scope parameter of an Business Connect authorization request.

state optional  #

A value that will be returned to you unaltered along with the authorization request decision.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement access_token before the request is retried.

422 Unprocessable #

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required email parameter, you would receive a response like:

{
  "errors": {
    "email": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

Example callback responses #

Successful authorization example #

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "authorization": {
    "code":  "{CODE}",
    "state": "{STATE}"
  }
}

The authorization.code returned can be redeemed for an access_token and refresh_token as if the code had been returned in response to a regular Authorization Request.

Note that the callback_url must be passed to the subsequent Access Token Request and may be passed as a parameter named callback_url (for consistency in this flow) or redirect_uri (if you want to share code for redeeming tokens between the different flows).

Failed authorization example #

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8

{
  "authorization": {
    "error": "access_denied",
    "error_key": "unknown_email",
    "error_description": "Unknown user or email"
  }
}

Request parameters #

authorization.error  #

The type of error, always access_denied to indicate the authorization request failed.

authorization.error_key  #

The specific reason for the authorization failure. For example:

• unknown_email no account or resource was found with the given email and so authorization should not be reattempted