Authentication

Every request to the Matter API must include a valid API token. Tokens are scoped to your account and give full read/write access to your library.

Getting your token

Your token looks like this:

mat_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8

The mat_ prefix identifies it as a Matter API token. If you ever see one in logs or code, you know what it is.

Pass the token in the Authorization header on every request:

curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer mat_your_token_here"

Never share your token or commit it to source control. Treat it like a password. Use environment variables or a secrets manager.

Action	What happens
Generate	Creates a new token. Any previous token is immediately revoked.
Regenerate	Invalidates the old token and issues a new one.
Revoke	Destroys the token. API access stops immediately.

You can have one active token at a time. Generating a new token automatically revokes the previous one.

Store tokens in environment variables

export MATTER_API_TOKEN="mat_your_token_here"

curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer $MATTER_API_TOKEN"

Use .env files for local development

# .env (add to .gitignore!)
MATTER_API_TOKEN=mat_your_token_here

Rotate tokens periodically

If you suspect a token has been exposed, regenerate it immediately in your settings.

If authentication fails, the API returns 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API token."
  }
}

If your account doesn’t have an active Pro subscription:

{
  "error": {
    "code": "forbidden",
    "message": "The Matter API requires an active Pro subscription."
  }
}

⌘I