Versions: 1.0 | 1.1 | 1.2 | 1.3 | 2.0 | 3 | 4 | Authentication documentation

Authentication Mechanisms

Customer Token

Every customer can have one or more customer tokens. The token gives you unlimited access to all the API endpoints on behalf of any user visiting the site.

How it works: once you obtain a token, you can send a request like

curl '' -H 'Authorization: Token <token>:<user_id>'

WARNING: the token should never be used within client-side apps such as mobile, desktop or browser applications, it's only intended for secure server-to-server communication.


Step 1 - App Registration

  1. Login to the Spotlight domain as Admin.

  2. Register the application at https://<spotligh_domain>/oauth2/applications/register/

  3. Specify the below parameters when creating a new application -

    • Name: App name
    • client_type: 'confidential'
    • Authorization grant type: 'Authorization code'
    • Redirect URI: Where spotlight will redirect after the authentication flow is complete
  4. A client id and client secret is automatically generated for the app.

  5. Please note that the registered app will be linked to the spotlight domain used to create the app.

Step 2 - Generate Authorization Code

Spotlight provides OAuth2 support. Once you authenticate and generate a new user token, you can use it to make requests

  1. The authorization endpoint is https://<spotlight_domain>/oauth2/authorize/

  2. Submit a GET request to the authorization end point - https://<spotlight_domain>/oauth2/authorize/?client_id=<client_id>&response_type=code&redirect_uri=<redirect_uri>

  3. User needs to follow the autorization flow in the browser.

  4. Once Spotlight has successfully authenticated the user, a dialog will prompt the user to authorize the app. If the user clicks "Allow", app will be authorized. The OAuth 2 dialog will redirect the user's browser via HTTP 302 to the redirect_uri with an authorization code: http://[:redirect_uri]?code=[:code].

Step 3 - Generate Access Token

  1. The token endpoint is https://<spotlight_domain>/oauth2/token/.

  2. Submit a POST request to the token endpoint with the below parameters -

    • client_id: <app client id>
    • client_secret: <app client secret>
    • redirect_uri: <oauth_client_redirect_uri>
    • grant_type: 'authorization_code'
    • code: <code>
  3. An access_token is returned in the response which can be used to make further request to the API.

Step 4 - Making requests

curl '<access_token>'

OAuth2 provider issues tokens to users directly, so the token has information about the user. This token can then be stored in user storage (e.g. mobile phone).


Filtering and ordering

In most cases, listing endpoints allow you to order the results and filter them. For ordering, use order parameter. It usually accepts at least created and modified. To reverse the order, just put - before it (e.g. -created).

For filtering, lots of options are available. For example, to filter ideas by number of comments, use num_comments parameter. Its format: [min_value]..[max_value], either minimal or maximal value can be omitted.