Organization authentication

Partners can create an admin token that is valid for twenty-four hours to authenticate any requests sent during that time for a specific organization. This means that you can give users access to organization-level API calls without creating a role for them.


The call used to create this shared organizational token must be made by a user who is defined as a partner in the system. If you do not have partner credentials, reach out to your technical account manager to receive the proper credentials.

To create a token for the entire organization, you will need:

  • to ensure you’ve already created the organization
  • your basic authentication token
  • a JSON web token (JWT) – enables access to Surfsight resources, including your organization’s data; Independently generate this token using the HS256 algorithm from the JWT site

Authentication tokens only work for the environment to which you are registered. For example, a user registered to the US cloud receives tokens for that cloud, and not the EU cloud.

To generate an admin token for an organization:

  1. Create an organization using the POST /organizations call.

    curl --request POST
        --header 'Content-Type: application/json'
        --header 'Authorization: Bearer {token}'
          "name": "organization 1"

    The API request returns two keys:

    • ssoSecret
    • organizationld

    Securely store the ssoSecret on your backend database. It is not stored on the Surfsight system.


    Save the organizationID to use in other calls. You can also get the ID again from the GET /organizations call.

  2. Create a JWT token. You can use the JWT site.

The following parameters must be set:

-current timestamp, in the format of YYYY-MM-DDThh:mm:ss



A JWT is returned. This is the token you will use in the next step.


The JWT token is valid for fifteen minutes. Use the HS256 algorithm when generating this token.

  1. Request an admin token with the GET /organizations/sso call.

    Provide your JWT token in the authorization header.

    curl --request GET
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {JWT token}'

    An authentication token is returned. This is the authentication token you will use for subsequent calls.


    The admin token that is returned is valid for twenty-four hours.

  2. In any subsequent call, include the header, using the following structure:

    --header 'Authorization: Bearer e3d53477-1f85-42c1-8ed0-2bb591700db8'

    Following is an example of the GET /organizations call, with the token in the header.

    curl --request GET
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer e3d53477-1f85-42c1-8ed0-2bb591700db8'