Authentication

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 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.

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.

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.

{
    "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:

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) handles all of the authentication logic automatically. Initially authenticate using the refresh token by using the authenticate method:

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.

Contents