All API calls have to be authenticated with a valid Grape user account.

There are three ways to authenticate and it depends on your needs what you use.

  • HTTP Basic Authentication
  • Session ID cookie
  • Auth Token

Authentication Methods

Username and password via HTTP Basic Authentication

HTTP Basic Authentication (Wikipedia)

Send username and password in clear text. This is used as to receive the API Token for example.

Auth Token in HTTP header

HTTP Header: Authorization: Token YOUR_TOKEN

Example: Authorization: Token e38fe33ddc558f31df51dcae19edbe301fc0754f

the token lives forever and this is recommended for Apps and server side software using our APIs.

Notes on Authentication

The authentication methods work for using the Chat API via HTTP and via Websockets and also for our REST API.

Note on Websockets: the packet to initiate the Websocket connection looks like a HTTP packet and supports all three authentication methods. The browser automatically sends cookies with Websocket connections. The individual RPC calls going over the Websocket connection need no more authentication.

REST API to get session id or token


curl Example

Basic Authentication

  • Username: User-4
  • Passwort: test
curl --user User-4:test

Token Authentication

  • Token: e38fe33ddc558f31df51dcae19edbe301fc0754f
curl -H "Authorization: Token e38fe33ddc558f31df51dcae19edbe301fc0754f"


Successful response (JSON):

  "authtoken": "e38fe33ddc558f31df51dcae19edbe301fc0754f",
  "sessionid": "7e9o4zbjh6dylwvy2ny4d4g9geu98qtn",
  "user": {
    "username": "user-4",
    "first_name": "John",
    "last_name": "Kovačević",
    "display_name": "John Kovačević",
    "email": "",
    "avatar_url": "",
    "id": 14
  "next": [
      "url": "/accounts/organization/dashboard/",
      "reason": "create-organization"

Possible errors

Error response (JSON):

  "detail": "Invalid username/password"

Possible error messages:

Basic Auth

  • ‘Invalid basic header. No credentials provided.’
  • ‘Invalid basic header. Credentials string should not contain spaces.’
  • ‘Invalid basic header. Credentials not correctly base64 encoded’
  • ‘Invalid username/password’

Token Auth

  • ‘Invalid token header. No credentials provided.’
  • ‘Invalid token header. Token string should not contain spaces.’
  • ‘Invalid token’
  • ‘User inactive or deleted’