# 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: - 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](/developers/api/enterprise-connect/request-authorization/index.md) request.
    - 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](/developers/api/authorization/request-token/index.md) API - Note that the `callback_url` must be passed in place of the `redirect_uri`
      - Use the tokens in the same way as those retrieved via [the standard OAuth authorization flow](/developers/api/authorization/index.md) #### URL format ``` {data_center_url}/v1/service_account_authorizations ``` #### Example request for a single email address ```http 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 ```http 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 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 ##### `data_center_url` *(required)* The URL for the data center you want to communicate with. Possible choices are: - `api-au.cronofy.com` - Australia - `api-ca.cronofy.com` - Canada - `api-de.cronofy.com` - Germany - `api-sg.cronofy.com` - Singapore - `api-uk.cronofy.com` - United Kingdom - `api.cronofy.com` - United States Find out more about [Cronofy's data centers](/developers/data-centers/index.md). ##### `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](/developers/api/enterprise-connect/delegated-access/index.md) 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](/developers/api/enterprise-connect/request-authorization/index.md). ##### `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](/developers/api/authentication/index.md) were not recognized. When an OAuth `refresh_token` is available then it should be used to [request a replacement Service Account `access_token`](/developers/api/enterprise-connect/refresh-token/index.md) 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: ```json { "errors": { "email": [ { "key": "errors.required", "description": "required" } ] } } ``` The `key` field is intended for programmatic use and the `description` field is a human-readable equivalent. ### Example callback responses #### Successful authorization example ```http 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](/developers/api/authorization/request-authorization/index.md). Note that the `callback_url` must be passed to the subsequent [Access Token Request](/developers/api/authorization/request-token/index.md) 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 ```http 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 --- [Read in HTML](/developers/api/enterprise-connect/delegated-access/)