> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate to the Maia API

export const maia = "Maia";

This document provides essential information on setting up and authorizing API credentials for your {maia} account with the {maia} API.

## Prerequisites

* A {maia} account.
* Valid API credentials.
* Only users with the [Manage API Credentials](/docs/administration/account-roles#:~:text=Manage%20API%20Credentials) permission can create API credentials.

<Note>
  - Each account must have at least one user with the **Super Admin** role at all times. Removal or changes to a user with the **Super Admin** role must be done by another user with the **Super Admin** role.
  - Accounts created before December 2024 do not have a **Super Admin** user automatically assigned. If you wish to elevate an existing user to have the **Super Admin** role, raise a [Support ticket](https://support.matillion.com/s/). For more information, read [Getting support](/docs/guides/getting-support).
</Note>

***

## API credentials

The {maia} API uses the following credentials:

* **Client ID:** The unique public identifier associated with your {maia} account. This is automatically generated when you create the credentials and is visible for the lifetime of the credentials.
* **Client Secret:** The unique password required to access the API. This is not visible after it has been generated.
* **API Token:** You will need to request an API token using your Client ID and Client Secret as part of the authentication process, which is detailed later. An API token is valid for 30 minutes. You can request a new token when one expires.

***

## Create and configure API credentials

You can create multiple sets of API credentials for an account and assign a specific role to each set. Read [Account roles for API credentials](/docs/administration/api-credentials#role-permissions) to learn more about roles.

To create and configure API credentials, follow these steps:

### Step 1: Generate API credentials

1. Log in to [{maia}](/docs/administration/registration).

2. In the left navigation, click your Profile & Account icon. Then, select **API credentials** from the menu.

3. Click **Set an API Credential** to begin the process of creating your Client ID and Client Secret.

4. Give your credential set a descriptive **Name** and select an **Account Role** which defines the permissions for the set. For information about the available roles, read [Account roles for API credentials](/docs/administration/api-credentials).

   <Note>
     * We recommend that you use a name that suits the application or purpose the credentials will be used for.
     * If the credential is assigned an account role other than **Super Admin**, you must also grant the API credential specific roles on each project and environment it needs to access, just as you would for a standard user.
   </Note>

5. Click **Save** to create the Client ID and Secret.

6. **Copy** the secret immediately. You are **not** able to view the secret again after this point. If you do not copy it, or otherwise lose it, you will need to delete these credentials and generate a new set. The **Secret** window will close automatically after this point.

### Step 2: Request an API access token

1. Configure a POST request to the following URL:

   `https://id.core.matillion.com/oauth/dpc/token`

2. Include the following snippet in the request body. You will require the Client ID and Client Secret you created earlier.

   ```bash theme={null}
   curl --location 'https://id.core.matillion.com/oauth/dpc/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'client_id=<CLIENT_ID>' \
   --data-urlencode 'client_secret=<CLIENT_SECRET>' \
   --data-urlencode 'audience=https://api.matillion.com'
   ```

Replace `<CLIENT_ID>` and `<CLIENT_SECRET>` with the corresponding values.

cURL command for getting a token:

```bash theme={null}
curl -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&client_id=<YOUR_CLIENT_ID>8&client_secret=<YOUR_CLIENT_SECRET>" \
    -X POST https://id.core.matillion.com/oauth/dpc/token
```

<Note>
  Depending on your operating system, the `cURL` command uses a different line continuation character:

  * Windows (PowerShell), use `^`.
  * macOS/Linux (bash/zsh), use `\`.
</Note>

### Step 3: Obtaining an API access token

The response will be a JSON object containing the access token. Note that this token will expire after 30 minutes.

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYTzUtTWtvM0hPYWtJRkdIeXNCSFp2RnQ5SElYRzcxWmhudlJjVnc4UEtvIn0...",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "pipeline-execution"
}
```

### Step 4: Making the request

Use the obtained access token to make requests to the API. Example request to get the list of projects:

```bash theme={null}
curl --location 'https://eu1.api.matillion.com/dpc/v1/projects?page=0&size=25' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
```

Replace `<ACCESS_TOKEN>` with the actual value of the access token.

Example cURL request:

```bash theme={null}
curl -X GET "https://us1.api.matillion.com/dpc/v1/projects" `
     -H "Content-Type: application/x-www-form-urlencoded" `
     -H "Authorization: Bearer <example_bearer_token>" `
     -d "page=0&size=25"
```

<Note>
  * Tokens have a limited lifespan; ensure to manage and refresh them accordingly.
  * Depending on your operating system, the `curl` command uses a different line continuation character:
    * Windows (PowerShell), use `` ` ``.
    * macOS/Linux (bash/zsh), use `\`.
</Note>

***

## Delete existing API credentials

To delete existing API credentials, follow these steps:

1. Log in to [{maia}](/docs/administration/registration).
2. In the left navigation, click your Profile & Account icon. Then, select **API credentials** from the menu.
3. In the credentials row, click the **Delete** icon.
4. In the **Delete API Credential** dialog, click **Delete**.

<Warning>
  Deleted API credentials cannot be recovered or restored. Deleting API credentials may break any integrations with API consumers that use these credentials.
</Warning>

***

## Get access token using Postman

Retrieve your access token by testing and interacting with the {maia} API collection using Postman. Follow these steps:

1. Click the **Run in Postman** button provided below.
2. In your Postman dashboard, navigate and select the `Post access token` endpoint. This section comes pre-filled with parameters and headers.
3. In the Body section, provide your {maia} account's **client ID** and **client secret**.
4. Click **Send**, and your access token is ready for use.

To use access tokens for authenticating API endpoints and testing an endpoint, refer to the [API reference user guide](/docs/api-reference/maia-api-overview).