How to Obtain a Token for API Authentication
The appliance relies on token-based authentication for all its APIs. This means that every user must include their API token in all API requests.
An existing user can get an API token if their user account is active on the appliance, and if they are not locked out of the appliance because of login security settings at the time of requesting a token.
If a user does not have an account on the instance, or if their account exists but is not active, they will not be able to receive an API token. If this happens, contact the appliance administrator.
Regular users can request their API token via the Authentication API.
Administrators can use the Authentication API to request a token, or they can use the options on the Administration ‣ Tokens page.
Obtaining a token via Authentication API (All users)
POST /api-token-auth/
Administrators and regular users can request an API token by sending a request to the Authentication API.
Users must submit their Spectra Analyze username and password in a POST request to the Authentication API endpoint on the same instance where their user account has been created.
An authentication token is not required for requests to this API.
If the request has succeeded, the Authentication API responds with a status code 200 and the user’s token in the response body. Users should copy and save this token, because it must be used in requests to all other appliance APIs.
Username and password are required for obtaining an API token. If any or both of those parameters are missing or incorrect in the request, the Authentication API responds with a status code 400 and an error message in the response body.
Request Format
Request Parameters
| NAME | REQUIRED | DESCRIPTION | TYPE |
|---|---|---|---|
| username | Required | Username of an existing, active account on the appliance instance for which the user wants to obtain an API token. | form, string |
| password | Required | Password of an existing, active account on the appliance instance for which the user wants to obtain an API token. | form, string |
Request Examples
Using these examples will expose the password in the shell history.
cURL
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl --request POST 'https://appliance.example.com/api-token-auth/' --form 'username="example_user"' --form 'password="example_password"'
Python
import requests
# Change the hostname in the URL
url = "https://appliance.example.com/api-token-auth/"
json = {'username': 'example_user', 'password': 'example_password'}
# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.request("POST", url, json=json)
print(response.text)
Response Format
Response Examples
{
"token": "988881adc9fc3655077dc2d4d757d480b5ea0e11"
}
The token received from the Authentication API must be used in the Authorization header when sending requests to all other APIs, for example:
curl -H "Authorization: Token 988881adc9fc3655077dc2d4d757d480b5ea0e11"
https://a1000.example.com/api/samples/B12B33EAA90E3A3C34D3366254224EA15CF9CC52/ticore/
Response Fields
| FIELD NAME | DESCRIPTION | TYPE |
|---|---|---|
| token | Authentication token for the user who sent the request. This token must be used in the Authorization header of all API requests. The token is tied to the user account, meaning it works only on the appliance instance where it was generated. | string |
Response Status Codes
| CODE | DESCRIPTION |
|---|---|
| 200 | OK |
| 400 | Unable to log in with provided credentials. |
Obtaining a token from the Spectra Analyze GUI (Administrators only)
In addition to using the Authentication API, administrators can obtain tokens and create tokens for other users from the General Spectra Analyze Administration page.
On the Administration page, click the Tokens icon to open the Tokens page. On the Tokens page, create a new token key by clicking the Add Token button to navigate to the Add token dialog.
Select the desired user and click the Save button.
The new key will be listed in the token table. The key can now be copied and inserted into requests to the Spectra Analyze APIs.
