> For the complete documentation index, see [llms.txt](https://docs.sign.enadocapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sign.enadocapp.com/evia-sign-api/v2/authorization-and-authentication/exchange-authorization-code-for-access-token.md).

# Exchange Authorization Code for Access Token

After successfully receiving the **authorization code**, the next step in the OAuth 2.0 flow is to exchange that code for an **access token**. This token acts as a credential that authorizes your application to securely access Evia Sign API endpoints on behalf of the authenticated  system.

The exchange must be performed by your backend server, using your **Client ID** and **Client Secret**, along with the received code. The resulting access token must then be included in the `Authorization` header of all subsequent API requests.

## Token Exchange URL

<mark style="color:yellow;">`POST`</mark> `/_apis/falcon/auth/api/v2/token`

This endpoint is used to exchange a valid **authorization code** for an **access token**.\
The access token is required to authenticate and authorize all subsequent API requests to the Evia Sign platform.

This request must be made server-side to ensure secure handling of the **Client Secret**.

### Request Headers

Include the following headers to authenticate your request and ensure it’s correctly processed by the server.

| Name          | Value                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Authorization | The `Authorization` header must use **Basic Authentication**. Format the value as: `Basic base64(client_id:client_secret)` |
| Content-Type  | Must be set to `application/x-www-form-urlencoded` to ensure that the request body is interpreted correctly by the server. |

### Request Body Parameters (Form-Encoded)

The request body should be sent in `x-www-form-urlencoded` format. Below are the required parameters:

| Parameter       | Required | Description                                                               |
| --------------- | -------- | ------------------------------------------------------------------------- |
| `grant_type`    | ✅ Yes    | Must be set to `authorization_code`                                       |
| `client_id`     | ✅ Yes    | Your application's **Client ID** (same used in the authorization request) |
| `client_secret` | ✅ Yes    | Your **Client Secret**                                                    |
| `code`          | ✅ Yes    | The **authorization code** received from the previous step                |

### Sample Request (Raw Format)

```http
POST https://evia.enadocapp.com/_apis/falcon/auth/api/v2/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
```

#### **Body**

```json
{
  "grant_type": "authorization_code",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "code": "received-auth-code"
}
```

### Successful Response

If the request is valid, Evia Sign will return a response with an access token:

```json
{
  "access_token": "abc123...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "xyz456..."
}
```

| Field           | Description                                                                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`  | This is the actual token your app will use to make authorized API requests. You must include it in the `Authorization` header as `Bearer abc123...` |
| `token_type`    | Always set to `bearer`. This just tells you how the token should be used in the header                                                              |
| `expires_in`    | The number of seconds the access token is valid for. In this case, 7 days. After that, the token is no longer valid.                                |
| `refresh_token` | A token that can be used to request a new `access_token` after it expires—so your app doesn’t need to go through the full authorization flow again. |

### Error Response Example

```json
{
  "error": "invalid_request"
}
```

Common causes include:

* Missing or incorrect `client_id` or `client_secret`
* Expired or reused authorization code
* Incorrect or mismatched `redirect_url`

## Using the Access Token in API Requests

Once the access token is received, include it in the `Authorization` header of all subsequent API requests:

```http
Authorization: Bearer abc123...
```

This token allows Evia Sign to verify the identity of your registered application and authorize its access to the API, based on the scopes granted during app registration.

## Refresh Access Token

After the original `access_token` has expired, you can request a new one using a valid `refresh_token`. This allows your application to maintain its authenticated session with the Evia Sign API **without re-running the full authorization flow**.

### Request URL

&#x20;<mark style="color:yellow;">`POST`</mark>`/ _apis/falcon/auth/api/v2/Token`

This endpoint is used to exchange a valid refresh token for a new access token.\
The request must be made **server-side**, as it involves sending your Client ID and Client Secret in the `Authorization` header.

### Request Headers

| Header          | Required | Description                                                          |
| --------------- | -------- | -------------------------------------------------------------------- |
| `Authorization` | ✅ Yes    | Basic Auth using `base64(client_id:client_secret)`                   |
| `Content-Type`  | ✅ Yes    | Handled automatically as `multipart/form-data` via the `--form` flag |

```http
Authorization: Basic Base64(client_id:client_secret)
Content-Type: multipart/form-data
```

### Request Body Parameters&#x20;

| Parameter       | Required | Description                                                      |
| --------------- | -------- | ---------------------------------------------------------------- |
| `Refresh_Token` | ✅ Yes    | The valid refresh token previously issued by Evia Sign.          |
| `Grant_Type`    | ✅ Yes    | Must be set to `Refresh_Token` (case-sensitive on some systems). |

```http
Refresh_Token: "457F4F73-025C-451A-8484-674C5FDC11B59F421000-10CD-4B3E-871D-586EFD38139C"
Grant_Type: "Refresh_Token"
```

### Successful Response

```json
{
  "access_token": "new-access-token-123...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "new-refresh-token-456..."
}
```

### Error Response

```json
{
  "error": "invalid_request"
}
```

**Possible causes:**

* Missing or expired `Refresh_Token`
* Incorrect `Grant_Type`
* Invalid or malformed `Authorization` header

### Using the New Token

Once you receive the new `access_token`, include it in the `Authorization` header like this:

```http
Authorization: Bearer new-access-token-123...
```