Authentication

Self-hosted Umami supports two ways to authenticate API requests. API keys are the recommended method. Username and password authentication is still supported as an alternative.

For Umami Cloud, API keys are the only authentication method. See API key.

API keys (recommended)#

API keys are long-lived credentials that are ideal for programmatic access. They don't expire and can be revoked individually.

Create a key#

Generate a key from the app by clicking your profile icon, selecting Settings, and navigating to API keys. Click Create key and save the value — it is only shown once.

You can also create, list, and delete keys programmatically:

• Create an API key
• List my API keys
• Delete an API key

Using your key#

Pass the key with an Authorization header using the Bearer authentication scheme.

Authorization: Bearer <api-key>

For example, with curl it would look like this:

curl https://{yourserver}/api/websites \
   -H "Accept: application/json" \
   -H "Authorization: Bearer <api-key>"

Username and password (alternative)#

If you prefer, you can still authenticate by exchanging your username and password for a temporary token.

POST /api/auth/login#

First you need to get a token in order to make API requests. You need to make a POST request to the /api/auth/login endpoint with the following data:

{
  "username": "your-username",
  "password": "your-password"
}

If successful you should get a response like the following:

{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
  "user": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "username": "admin",
    "role": "admin",
    "createdAt": "2000-00-00T00:00:00.000Z",
    "isAdmin": true
  }
}

Save the token value and send an Authorization header with all your data requests with the value Bearer <token>. Your request header should look something like this:

Authorization: Bearer eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A

For example, with curl it would look like this:

curl https://{yourserver}/api/websites \
   -H "Accept: application/json" \
   -H "Authorization: Bearer <token>"

The authorization token is expected with every API call that requires permissions.

POST /api/auth/verify#

You can verify if the token is still valid.

Sample response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "admin",
  "role": "admin",
  "createdAt": "2000-00-00T00:00:00.000Z",
  "isAdmin": true,
  "teams": []
}