# 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...
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sign.enadocapp.com/evia-sign-api/v2/authorization-and-authentication/exchange-authorization-code-for-access-token.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.