<!-- Source: https://docs.squirro.com/en/latest/technical/api/authentication.html -->
# Authentication

All Squirro API resources are protected and authentication credentials for HTTP authentication (using the _Authorization_ header) are mandatory.

The caller needs to use generated user tokens with HTTP [Basic Access Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication) or use bearer tokens in HTTP requests to access the protected resources.

## User Token

To authenticate with the Squirro platform the caller needs a user token. That token can be generated in the “API Access” section of the Squirro settings. The resulting user token provides access according to the rights of the user.

## Using the Token in the API

In the context of the API the user token is called a refresh token. To use the API, a refresh token can not be used directly. Instead, an access token needs to be generated.

Note: The access token expires very quickly (10 minutes by default), whereas the refresh token does not expire.

## Create Access Token

`POST https://squirro-server/api/user/oauth2/token`

Log into Squirro using a refresh token.

|  |  |
| --- | --- |
| Form Parameters: | - **grant_type** – Set to `refresh_token`. - **refresh_token** – The user’s refresh token. |
| Headers: | See [Common Headers](common-headers.md#api-common-headers). |
| Status Codes: | - **404** – Invalid refresh token. - **410** – Refresh token expired (e.g. token was expired due to a security reason). See also [Common Status Codes](common-status.md#api-common-status). |
| Returns: | A new user session. The `access_token` field can be used for further API requests. The role permissions show the permissions, the user has in the tenant. ```javascript { "project_permissions": [ "*", "frontend.user" ], "user_id": "qjsRI0s0XVGli8qPPCjKzw", "access_token": "882d9b12cce019ee0137e54beaeea2227db4db3e", "session_id": "M9cRgRXUSSOpe_F0YRwdmg", "role": "admin", "refresh_token": "200…3c3", "role_permissions": [ "admin", "profile.write.update", "projects.write.create" ], "tenant": "squirro_demo" } ``` |

## Use Access Token

To use the access token with any of the API requests, the access token needs to be passed in with the `Authorization` header, prefixed with the token “Bearer”.

Example HTTP request:

```text
GET /api/topic/v0/squirro_demo/projects HTTP/1.1
Host: squirro-server
Accept: application/json
Authorization: Bearer 882d9b12cce019ee0137e54beaeea2227db4db3e
```

## Squirro Client

The [SquirroClient (Python SDK)](squirro_client/index.md#squirro-client) handles all of the authentication logic automatically. Initially authenticate using the refresh token by using the `authenticate` method:

```python
client = SquirroClient(None, None, cluster='https://squirro-server')
client.authenticate(refresh_token='200…3c3')
```

The client will retrieve an authentication token and use that for all subsequent requests. When the token expires, the client will re-authenticate using the refresh token and retry the failed request.