# Authentication

> Obtain a bearer token, then send it with every request

---

Site [llms.txt](/llms.txt)

---

The API uses the same accounts and permissions as the rest of Cloud Management Platform (CMP): the roles and group permissions that apply in the web interface also apply to the API.

## Prerequisites

An account you can log in to the web interface with. Every user has API access.

## Get a bearer token

### With curl

Replace `cmp-ip-or-hostname`, `username`, and `password`. Include `domain` only when logging in against a directory domain.

```bash
curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","password":"<password>","domain":"<domain>"}' \
  "https://<cmp-ip-or-hostname>/api/v3/cmp/apiToken/"
```

The response contains `token`, the short-lived *access* token you send with each request, and `refreshToken`, the longer-lived one you exchange for a new access token.

```json
{
  "token": "<access-token>",
  "refreshToken": "<refresh-token>"
}
```

### With the API console

<div class="alert alert-info" role="alert">


You must be logged in to CMP to use the API console.
</div>


1. Go to `/api/v3/cmp/apiToken/` on your CMP address, for example `10.11.12.13/api/v3/cmp/apiToken/`.
1. In the **POST Data** content field, supply your `username` and `password`, and `domain` if you use one:

   ```json
   {
     "username": "{{username}}",
     "password": "{{password}}",
     "domain": "{{domain}}"
   }
   ```

1. Select **POST**.

## Pass the token with each request

Send the access token in the `Authorization` header:

```text
Authorization: Bearer {{access_token}}
```

<div class="alert alert-info" role="alert">


HTTP Basic authentication is disabled by default. If a legacy script depends on it, it can be re-enabled in `customer_settings.py`.
</div>


## Refresh an expired token

Access tokens are short-lived. Exchange the refresh token for a new access token by posting it to `/api/v3/cmp/apiTokenRefresh/`. The refresh token goes in a field named `token`:

```json
{
  "token": "<refresh-token>"
}
```

The response returns the new access token, again as `token`:

```json
{
  "token": "<new-access-token>"
}
```

Once the refresh token expires, request a new pair with your credentials.

## Token lifetimes

A token pair has two components, each with its own default lifetime.

| Token type | Default lifetime |
| --- | --- |
| Access token | 5 minutes |
| Refresh token | 1 day |

### Change the token lifetimes

1. Define the `SIMPLE_JWT` dictionary in `/var/opt/cloudbolt/proserv/customer_settings.py`. It replaces the built-in one, so include both keys:

   ```python
   from datetime import timedelta

   SIMPLE_JWT = {
       "ACCESS_TOKEN_LIFETIME": timedelta(hours=24),
       "REFRESH_TOKEN_LIFETIME": timedelta(days=7),
   }
   ```

   <div class="alert alert-info" role="alert">


   You can use any `timedelta` unit, including seconds, minutes, hours, and days.
   </div>


1. Restart the web server to apply the change: `systemctl restart httpd`.

Tokens issued after the restart carry the new lifetimes. Tokens issued before it keep the old ones until expiry.

## Personal access tokens

A personal access token is an alternative to a bearer token and is useful when single sign-on means your users have no password to exchange for one. It is a long-lived token you generate from your user profile and send in the same header, with the `Token` scheme rather than `Bearer`:

```text
Authorization: Token <personal-access-token>
```

CMP endpoints accept either scheme. See [Authentication using personal access tokens](/docs/cmp/configure/access-and-security/security/api-personal-access-token/) for how to create, regenerate, and expire one.

## Authentication errors

Two status codes are specific to authentication:

- `401`: the token is missing, malformed, or expired. Obtain or refresh a token and retry.
- `403`: the token is valid, but the account does not have access. Check the user's permissions.

For the error body shared across all endpoints, see [Errors](/docs/cmp/developer-resources/rest-api/conventions/#errors) in API conventions.

## Extend the API

You can add your own endpoints to the CMP API with a plugin, using an inbound webhook. See [Inbound webhooks](/docs/cmp/use/orchestration/actions/inbound-webhooks/).

## Related

- [API conventions](/docs/cmp/developer-resources/rest-api/conventions/): URLs, identifiers, parameters, pagination, limits, and errors.
- [Authentication using personal access tokens](/docs/cmp/configure/access-and-security/security/api-personal-access-token/): creating a long-lived token.
- [Global roles](/docs/cmp/configure/access-and-security/groups-roles-permissions/global-roles/): the roles that apply across CMP and what each one grants.