> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1/authentication.md).

# Authentication

## Overview

All API requests use **token-based authentication**. To authenticate a request, include your API token in the `x-material-client-secret` authorizations header described in the [endpoint references](https://docs.material.security/reference/api-v1/issues).

#### Example

```http
GET /api/v1/issues HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_TOKEN
Accept: */*
```

### How it works

* Each API token is tied to a specific account. You can create as many tokens as needed.
* Tokens created when you connect an AI tool through the Material MCP server appear in the same list, marked as MCP connections.
* The token identifies who is making the request.
* Requests are checked against the account's current permissions, not the permissions it had when the token was created. The token identifies the account, but it doesn't grant any permissions on its own.

{% hint style="success" %}

#### Material token best practices

* Keep your API token secure and treat it like a password
* Do not expose tokens in client-side code or public repositories
* Rotate tokens periodically
* For production use, create a dedicated service account for generating API tokens
  {% endhint %}

#### Errors

If authentication fails, the API will return a `401 Unauthorized` response. One common cause is missing the `x-material-client-secret` header.

***

## Create a new token

{% hint style="info" %}

* For production use, we recommend creating a new service account to generate the API token. Once the token is created, you can reset and discard the account's login details.
* We don't recommend creating tokens for Super Admins or Tenant Admins.
* Any role can create an API token for their account, but only Super Admins and Tenant Admins can create or modify tokens for other accounts.
  {% endhint %}

1. Log in to Material.
2. From the top toolbar, click **Integrations** (the puzzle icon).
3. Expand **API and MCP** > **Tokens and MCP Connections**.
4. Click **Create Token**.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FLGNqRh4rmzriXamdg4UC%2Fimage.png?alt=media&amp;token=f054180a-cd01-4bb9-9193-9573e2e94193" alt=""><figcaption></figcaption></figure>
5. Name the token descriptively, then click **Create Token**. It's useful to include a use case if you have many tokens stored.
6. Click the token box to copy the token to your clipboard, then store it safely. Use the token in the `x-material-client-secret` header.

<details>

<summary>Disable admin token creation</summary>

You can disable token creation for admins entirely if needed.

1. Log in to Material.
2. From the top toolbar, click **Integrations** (the puzzle icon).
3. Expand **API and MCP** > **Tokens and MCP Connections**.
4. Toggle **API Tokens** off:

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2Fp0qjqiBXFafbosUlGUe1%2Fimage.png?alt=media&amp;token=694d4dae-2080-40b3-a019-7086781886fa" alt="" width="303"><figcaption></figcaption></figure>

</details>

***

API related events are listed in the Audit Log. You can also quickly navigate to token specific events via the tokens list:

1. From **Tokens**, select **one** token row.
2. Click **View Audit Events.**
3. The Audit Log opens, pre-filtered to this token's events within the last week. Update the filter as needed.

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FCSNt8i4Hcbk9uE7TcHjp%2Fimage.png?alt=media&amp;token=def90658-4eb3-49c0-bf84-7bbdecc015aa" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The filtered audit log shows results for a single token. Since accounts can have multiple tokens, it may not include all events for a given user.
{% endhint %}

***

## Authentication Errors

If your API token is missing or invalid, the API returns a `401 Unauthorized` response. Verify that the `x-material-client-secret` header is present and that the token is correct. A missing header is the most common cause.

If the token is valid but the account behind it lacks permission for what you're calling, the API returns `403 Forbidden` instead. Reading accounts and groups needs directory read permission, and changing role assignments needs role-management permission on top of it. See [Admin Roles](https://docs.material.security/learn-more/administration/admin-roles) for what each role allows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.material.security/reference/api-v1/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.