Request User/Resource Access

Description #

When authenticated for an Enterprise Connect account, 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 call to the /service_account_authorizations endpoint with the desired scope.

• The scope should match the delegated_scope that has previously been granted via Service Account Authorization request.

2. Trade the code you received in the response for a set of Access and Refresh Tokens for the account or resource by calling the Request an Access Token API

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

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

URL format #

{data_center_url}/v1/service_account_authorizations

Example request for a single email address #

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

{
    "email" : "{EMAIL_OF_DELEGATED_ACCOUNT}",
    "callback_url": "{CALLBACK_URL}",
    "scope" : "{SCOPES}",
    "state": "{STATE}"
}

Example request for a collection of email addresses #

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

{
    "service_account_authorizations": [
        {
            "email" : "{EMAIL_OF_DELEGATED_ACCOUNT_1}",
            "callback_url": "{CALLBACK_URL_1}",
            "scope" : "{SCOPES_1}",
            "state": "{STATE_1}"
        },
        {
            "email" : "{EMAIL_OF_DELEGATED_ACCOUNT_2}",
            "callback_url": "{CALLBACK_URL_2}",
            "scope" : "{SCOPES_2}",
            "state": "{STATE_2}"
        }
    ]
}

Parameters such as callback_url can be different or identical for each entry as suits your integration. Only the email parameter needs to differ. A mix of single and collection formats is not permitted.

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 #

service_account_authorizations optional  #

Allows a batch of 1 to 50 access requests to be submitted at the same time.

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 Enterprise 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 Service Account 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, currently one of:

• access_denied indicating the authorization request failed.
• sync_failing indicating that some permissions issue is preventing the calendar from being synced. This can occur multiple times as the request is retried. Permissions between the Service Account and resource need to be reviewed.
• request_expired the calendar could not be synced after multiple retries over several hours. The request has expired and will not be retried any longer. A new request can be made once any permissions issues are resolved.

authorization.error_key  #

The specific reason for the authorization failure. More values may be added in the future as we improve our detection of failure cases.

Currently one of:

• account_disabled an account was found but it was flagged as disabled by the provider
• account_read_only permission was denied attempting to create events in calendar
• cannot_find_calendar the calendar folder for the requested account could not be found
• cannot_impersonate_self the service account email was specified as the delegated resource
• cannot_resolve_email failed to resolve requested email address when testing event creation
• cannot_resolve_server_hostname DNS resolution for the calendar server failed
• impersonation_denied the service account has been unable to impersonate the requested user
• non_primary_email the account being impersonated must be requested using its primary email address
• server_error the calendar server reported an internal error
• unable_to_grant_scope the service account lacks the permissions to grant the requested scopes
• unauthorized_request service account authentication has failed with an Unauthorized response
• unknown_email no account or resource was found with the given email and so authorization should not be reattempted