> 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.
* The token identifies who is making the request.
* Requests are checked against the account's current permissions—not the permissions they had when the token was created. The token identifies the account, but doesn’t grant any permissions on its own.

{% hint style="success" %}

#### Material token best practices

* Keep your API token secure—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** > **Tokens**.
4. Click **Create Token**.

   <figure><img src="/files/cCKeJ1Tb5E3yosMLyaFD" 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** > **Tokens**.
4. Toggle **API Tokens** off:

   <figure><img src="/files/Ek1n6fwICbltW5f7IdU2" 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="/files/fNO0fUfJzyuDXZu9EmiT" 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 key is missing or invalid, the API will return a `401 Unauthorized` response. Verify that the `x-material-client-secret` header is present and that the key is correct.


---

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