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.

Example

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.

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

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

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

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.

   
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.

Disable admin token creation

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:

   

---

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.

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.

---

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 for what each role allows.