# Delegated authorization

> **PRERELEASE**

#### Description
When authenticated as an account that has granted delegated authorization
through a [Business Connect authorization request](/developers/api-alpha/business-connect/request-authorization/index.md),
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 [Delegated Authorization request](/developers/api-alpha/business-connect/delegated-authorization/index.md)

- Receive a `code` via a request made to the `callback_url` provided to the access request

- Trade the `code` for access tokens for the account or resource by making an [Access Token Request](/developers/api/authorization/request-token/index.md)

- Note that the `callback_url` must be passed with the `code` 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/delegated_authorizations
```

#### Example request
```http
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
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).
##### `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](#example-callback-responses) 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](/developers/api-alpha/business-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 `access_token`](/developers/api/authorization/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, 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



---
[Read in HTML](/developers/api-alpha/business-connect/delegated-authorization/)