Observe API Authentication¶
Note
The bearer token format used for API authentication is different than that 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.
Obtaining a Bearer Token from your Observe Instance - Local Auth¶
You can generate a Bearer token 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":"[email protected]", "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
Obtaining a Bearer Token from your Observe Instance - SSO¶
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.
Example Request¶
curl -d '{"userEmail":"[email protected]", "integration":"observe-tool-abdaf0","clientToken":"testing via curl"}' https://${observe_tenant}.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 & 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.