📘
Note
The bearer token format used for API authentication is different than the format used by Datastream tokens.

Before you can interact with the Observe API, you must generate an access token via HTTP request (examples using cURL are below), or via the CLI. Observe uses Bearer tokens for authentication to its API. Bearer tokens are tied to specific users, and by default are valid for 30 days. API Tokens are also automatically renewed on use. However, if an API Bearer token goes unused long enough that its expiration will occur within 9 days or less, it will be extended as "valid" for 10 more days from the point of use. Token time to live is the same for Tokens generated via the CLI or via REST.

Obtain a bearer token for local authentication

You can generate a Bearer token from Observe using a cURL request with an email and password combination and the /v1/login endpoint.

Example request

For example, if you have a working login for an Observe instance such as a user email, testuser@example.com, and password, password123, create a bearer token using a command similar to the following example:

curl -H 'Content-Type: application/json' \
  https://123456789012.observeinc.com/v1/login \ 
  -d '{"user_email":"testuser@example.com", "user_password":"password123", "tokenName":"my testing token"}'

In the example, replace 123456789012.observeinc.com with the hostname of your Observe instance, and replace the email and password with your login credentials.

Example response

If successful, the response should be similar to the following key:

{"ok":true, "access_key":"1abCDE2FgHIJKLMNoPqrstuV3WXYZA4bc"}

This access key can be used for authentication in subsequent API requests, using an HTTP Authorization header formatted like the following:

Authorization: Bearer <CUSTOMER_ID> <ACCESS_KEY>

For example:

Authorization: Bearer 123456789012 1abCDE2FgHIJKLMNoPqrstuV3WXYZA4bc

Obtain a bearer token for SSO authentication

If you have integrated Observe with a supported SSO provider, generate an authtoken using cURL by following these steps.

Step 1 - Initiate a token request

Submit an HTTP POST request to your tenant at the following URL, replacing ${observe_tenant} with your 12 digit tenant ID. For the payload you can make the clientToken value anything. Note that the integration value is required and must be set to the static value observe-tool-abdaf0 as shown in the example.

Example request

curl -d '{"userEmail":"testuser@example.com", "integration":"observe-tool-abdaf0","clientToken":"testing via curl"}' https://${observe_tenant_name}.observeinc.com/v1/login/delegated

Example response

{"ok":true,"url":"https://$\{observe_tenant}.observeinc.com/settings/account?expectedUid=24007\u0026serverToken=P5J6GBLVG3XOXKK6LXJUWTB27UX6TJH6OCV6RNWT","serverToken":"P5J6GBLVG3XOXKK6LXJUWTB27UX6TJH6OCV6RNWT"}

Step 2 - login and approve

Open the url in the response in your browser, and login to your tenant. You should be in the "Account Settings" area of your tenant, with a pending approval request. Approve the request.

Step 3 - Retrieve your token

With the request approved, you need to append the serverToken value from step 1 to the below URL. This will return a response containing your API token, in the "accessKey" field.

Example request

curl -X GET https://${observe_tenant}.observeinc.com/v1/login/delegated/${serverToken}

Example response

{"ok":true,"settled":true,"accessKey":"O09J9WBhVl9Rd3t19TwEH919w6ImGDYT","message":"Login verified."}

This access key can be used for authentication in subsequent API requests, using an HTTP Authorization header formatted like the following:

Authorization: Bearer <CUSTOMER_ID> <ACCESS_KEY>

For example:

Authorization: Bearer ${observe_tenant} ${access_key}

Token expiration

Tokens last 31 days after minting. After 31 days, the token must be used at least once in every 24 hour period to remain active. After the first month has passed, an unused token will expire after one day.