Authentication

All requests against the Starmind API need to be authenticated. We use a token based authentication, where you receive a unique token after successfully logging in. This token is tied to your user and can be used as a "passport" in all subsequent requests until it expires.

We provide several ways how you can obtain a Token and interact with the API. What approach suits you best depends heavily on the integration you plan.

When should I choose what approach?

Server to Starmind Integration

The most common integration among our clients is a Server-to-Starmind setup that doesn't require any interaction of the user itself. This setup has a lot of potential and allows you to implement a lot of different features such as fetching open notifications for the user, update the user in the background .. etc. etc.

To do so you need to:

  1. Perform a simple login with username and password of a technical user.
  2. Store and reuse the bearer Token that is provided by the API.
  3. Perform actions "on behalf" of another user.

This approach requires a technical-user to have the roles api_user and on_behalf_user.

Browser-Client to Starmind Integration

Some clients choose to write an implementation which is running in the browser of the user itself. A good example is a JavaScript client (built on jQuery and Ajax) with a search field that directly interacts with the Starmind API.

You don’t want the users to have to enter a username and password every time they use this integration. For that purpose we support the possibility for privileged users to obtain Tokens for other users. You can then pass this Token to your JavaScript client and the user is able to interact with Starmind.

A technical user requires the role on_behalf_user to request Tokens for other users as described here.

Simple login with username and password

To obtain a token, you need an Api-Key as well as the email and password for your account. A technical user requires the role api_user in order to authenticate to the API.

The Api-Key can be provided via Header value (recommended) or Query-Parameter (not recommended)

The following shows an example with the api-key sent in the request header.

POST /auth/login
X-Auth-ApiKey: YOUR_API_KEY
Content-type: application/json

Body (application/json)

{
    "email": "sherlock@starmind.com",
    "password": "elementary"
}

We expect POST / PUT method body payloads always with Content-Type http request header application/json. If the credentials in the body or the provided api-key is invalid the API will respond with a HTTP Status Code 4xx and information about was what was wrong. Otherwise you will get a token object and HTTP Status Code 200.

Response (application/json)

{
    "token": "1d423a45b7e0466fb0a2c770450919e3070049c7",
    "expires": "43200"
}

There is a more detailed account of the errors under Error Handling.

Send the Token

The tokens won't be mentioned in the rest of the documentation, unless there is something out of the ordinary. It will just be assumed that you pass one along.

HTTP Authorization-Header You can simply add an Authorization Header to all of your api requests like this:

Authorization: Bearer 1d423a45b7e0466fb0a2c770450919e3070049c7

The Bearer token authorization method is recommended and will work with every API request.

HTTP Query-Parameter You can also pass the api-token as query-parameter auth_token for all of your api requests but this is not recommended since the token will be visible in webserver request logs.

GET /questions?auth_token=1d423a45b7e0466fb0a2c770450919e3070049c7

Generate Token for another user

If a technical user (has the role on_behalf_user) requires to obtain auth tokens for other user in the system, he can do this via this endpoint. A request for a token must be made using a valid admin token and the target user identifier.

POST /auth/user-token
Parameter Type Default Required Description
identifier string - unique user id or email address of the target user

Body (application/json)

{
    "identifier": "watson@starmind.com"
}

Response (application/json)

{
    "token": "1d423a45b7e0466fb0a2c770450919e3070049c7",
    "user_id": 42,
    "expires": "43200"
}

"Act on behalf" of another user

Security Warning

The "Act on behalf" functionality is very powerful and should be handled with care. A user with the role "on_behalf_user" can impersonate any other user and therefore execute any action this user is allowed to. We strongly recommend to keep this user confidential, set a strong password and change the password from time to time.
Don't use "Act on behalf" for background admin tasks

Never use the "Act on behalf" approach for background admin tasks such as updating profile information of the user base. An action performed with "Act on behalf" will result in a logged action as the impersonated user. As a result, this user will be considered activated, potentially having an impact on the subscription fee. Ask your Starmind Solution Architect for more details.

Sometimes you might want to work with a technical user for the API, acting on behalf of other users. This for example makes most sense if you call the API from an internal system where you control and ensure the authenticity of your users.

To allow a user to act on behalf of other users you have to specify the user identifier in the request header as a custom HTTP header using your regular API token.

In the background this will authenticate your user based on his token and if he's allowed to act on behalf of other users (has the role on_behalf_user it will just switch the user under the hood and all calls are handled as if the specified user makes the API calls himself.

Keep in mind that only one of the following X-Act-On-Behalf headers is allowed at once!

Act on behalf by ID (X-Act-On-Behalf)

To act on behalf of another user, specify the user's id as a custom HTTP header called X-Act-On-Behalf using your regular API token.

Act on behalf by Unique ID (X-Act-On-Behalf-Unique-Id)

To act on behalf of another user, specify the user's unique_id as a custom HTTP header called X-Act-On-Behalf-Unique-Id using your regular API token.

Errors

There is a more detailed account of the errors under Error Handling, but here is an overview what which HTTP status means.

HTTP Status Description
400 Bad Request No api-key was provided.
401 Unauthorized No token was provided, or the token is invalid/expired.
403 Forbidden You do not have access to this resource with this token.
404 Not found If you have requested a specific resource you don't have access to, we will return a 404 to hide the existence of the resource.
415 Unsupported Media Type If you sent a request with a not supported Content-Type. We expect POST / PUT method body payloads with Content-Type: application/json.