# Authentication

> Every API request carries a token from Identity, which proves who you are and is valid for one project until it expires.

Every API request carries a token. A token is a string that Identity issues when you
prove who you are with a password or an [application credential](/identity/application-credentials).
Services check the token with Identity, so you never sign in to them separately.

## What a token is valid for

A token belongs to one user and is scoped to one [project](/identity/projects). It carries the
roles you have in that project, and services use them to decide what you may do. A token is valid
until it expires or is revoked, whichever comes first. The `expires` field that Identity returns
with it shows when.

A token is not a long-term credential. Do not store one in configuration. Store an application
credential and get a new token from it when you need one.

## How services receive it

Services read the token from the `X-Auth-Token` header. This request asks Identity itself which
projects the token's user can access:

```http
GET /v3/auth/projects HTTP/1.1
Host: auth.vexxhost.net
X-Auth-Token: gAAAAABnA4tJq8r2Lw0m5X1zY7cT3vH9kQ6pN4sB2dF8gR0jU5eW1iO7aZ3xC9yV6nM4bK2lE8hG0fD5tS1uP7qA3wI9oJ6zL4cX2vN8mB5kR1yT7eU3iO9pS6dF2gH0jK4lZ8xC5vB1nM3qW7eR9tY2uI6oP0aS4dF8gJ
```

Some services also accept the token as `Authorization: Bearer`. Each API reference lists the
headers its service accepts.

The `openstack` CLI and the OpenStack SDKs get tokens for you, renew them before they expire, and
add the header to every request.

## When a token is refused

| Response           | Meaning                                                                | What to do                                                  |
| ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
| `401 Unauthorized` | The token is missing, has expired, was revoked, or is not a token.     | Get a new token and send the request again.                 |
| `403 Forbidden`    | The token is valid, but its project or roles do not allow the request. | Check which [project](/identity/projects) the token is for. |

Anyone who holds a token can act as you in its project until the token expires. Treat a token like
a password: do not log it, paste it into tickets, or commit it.

## Related pages

* [Get a token](/identity/get-a-token)
* [Create an application credential](/identity/application-credentials)