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.
Note
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
Note
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:
-
Create an organization using the
POST /organizations
call.curl --request POST https://api-prod.surfsight.net/v2/organizations --header 'Content-Type: application/json' --header 'Authorization: Bearer {token}' --data-raw { "name": "organization 1" }
The API request returns two keys:
- ssoSecret
- organizationld
attention
Securely store the ssoSecret on your backend database. It is not stored on the Surfsight system.
attention
Save the organizationID to use in other calls. You can also get the ID again from the
GET /organizations
call. - 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
-ssoSecret
-organizationId
A JWT is returned. This is the token you will use in the next step.
Note
The JWT token is valid for fifteen minutes. Use the HS256 algorithm when generating this token.
-
Request an admin token with the
GET /organizations/sso
call.Provide your JWT token in the authorization header.
curl --request GET https://api-prod.surfsight.net/v2/organizations/sso --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.
Note
The admin token that is returned is valid for twenty-four hours.
-
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 https://api-prod.surfsight.net/v2/organizations --header 'Content-Type: application/json' --header 'Authorization: Bearer e3d53477-1f85-42c1-8ed0-2bb591700db8'