Credential API Service
A public HTTP RESTful API service to create and manage tokens to access Synoptic products. This service is authenticated with your private key instead of a public token.
The credentials API should only be accessed from systems you control (e.g. not client applications) because it uses your private key.
Functions
This service uses any of the active API Keys on your account to
List active tokens (root endpoint)
Create new tokens (root endpoint)
Disable tokens (root endpoint)
Edit certain token settings (token endpoint)
Request Format
Should not be used by clients because it interfaces with your private API key, not tokens. Learn more about your API key here.
You can reach the credential API using this URL.
https://api.synopicata.com/auth/v2/
To manage token settings (not including creating or deleting tokens) use a URL of the following format
https://api.synopticdata.com/auth/v2/token/[a token value]
Other URLs have been supported in the past and will be supported for the immediate future, but we may reach out to you over time to update your endpoints. Particularly when we deploy version 3 of the credential service.
Authenticating
All requests must authenticate by including any private key associated with the account that owns the token. You authenticate this service in one of two ways.
You will receive an HTTP 401 error if authentication is unsuccessful and/or we cannot read the private key included.
Pass your private key via authorization bearer header
Include your private key in your request by including the API key as a bearer claim in an HTTP Authorization header.
Authorization: Bearer YourAPIKey
The header option is preferred as the payload of the request is exchanged more securely and appears in fewer logs than the URL, but both methods work and are supported.
Pass a private key via query string parameter
If you do not include an authorization header you can also pass a private key as a query string parameter apikey
/auth/v2/?apikey=YourApiKey
Root endpoint
This is the name for /auth/v2/
without any additional path (e.g. /token
) This endpoint will respond the same to any HTTP method - but we encourage using GET requests, as the service will not read for request payloads.
GET requests against the service directly will do one of 3 things depending on parameters
GET request variant - Create a token
To create a token, perform a GET request to the /auth
endpoint with only a combination of the following query string parameters (in addition to the apikey
parameter if using that method to authenticate)
Parameter | Format & example | Explanation |
---|---|---|
[no parameters] |
| Without any parameters passed, the service will create a new token for your account and return it in the format below. |
| YYYYmmddHHMM (UTC)
| a timestamp after which the token you are creating will no longer be valid. This value cannot be edited later. |
|
| Copy the settings from an existing token in your account to the token that will be created. An example use case for this is if you have a token with restricted functionality for a certain application, you can generate a new token with those same settings. If the specified settings token is invalid, deleted or expired, this service will return a 404 not found error. Learn about token settings. |
Response format
When a token is created the JSON response will be the following:
{
"TOKEN": "1672c91e97a7421f8ac67f7681d5810a"
}
This will be the response for these example requests.
/auth/v2/?apikey=ABC123
or /auth/v2/?apikey=ABC123&expire=123412010000
or /auth/v2/?apikey=ABCD1234&cloneSettings=abcdef12345
GET request variant - List tokens
The API can list your 100 most recent tokens. This service does not support pagination at this time, so there is no resource to list beyond 100 active tokens. You can have an unlimited number of tokens active on your account.
Include either of the following query string parameters to perform a list action.
Parameter | Format & example | Explanation |
---|---|---|
| 1 or 0, can be included without value
| Return a basic list of token values |
| 1 or 0, can be included without value
| Return a rich list of token metadata as a list of JSON objects. See response description below. |
Providing both parameters will result in listall
behavior. Cannot be combined with expire
, cloneSettings
, or disableToken
parameters (400 error).
Response format
Basic list
Always a list of strings under the TOKEN
key.
/auth/v2/?apikey=ABC123&list=1
{
"TOKENS": [
"cb39d7c75d3e45b1b98d3bf118831b98",
"52f74218e9d54f739adca46154ebcf80",
"f59b66e3c0814037ac610124ade2b11a"
]
}
List all
This function also uses the TOKEN
key, but returns a list of objects representing the tokens. These objects always have the token
key, and will have the following keys only if a value is present.
request
- token settings restricting the nature of HTTP requests made with it.tags
- A list ofname
,value
pairs representing the keys associated with the token. Note the special effect of theprotected
tag below.expire
- a timestamp for the expire time set when the token was created.
Not all settings are displayed.
/auth/v2/?apikey=ABC123&listall
{
"TOKENS": [
{
"token": "cb39d7c75d3e45b1b98d3bf118831b98",
"request": {
"http_origins": [
"https://synopticdata.com/"
]
},
"tags": [
{
"name": "protected",
"value": true
}
]
},
{
"token": "52f74218e9d54f739adca46154ebcf80",
"expire": "2028-01-01 00:00:00"
},
{
"token": "f59b66e3c0814037ac610124ade2b11a"
}
]
}
GET request variant - Disable a token
You can prevent a token from being used again by deleting it. This action cannot be undone. To do so make a request with standard authentication, and add the disable parameter.
New in September 2024: You cannot delete a token if the protected
tag is present in the token tags.
Parameter | Format & example | Explanation |
---|---|---|
| full token value to disable
| A token, owned by the account the private key represents, which should be deleted. |
Cannot be combined with any other parameters.
Response format
The delete request will respond with a simple object with a single key - MESSAGE
.
/auth/v2/?apikey=ABC123&disableToken=1672c91e97a7421f8ac67f7681d58142
{
"MESSAGE": "Token 1672c91e97a7421f8ac67f7681d58142 is disabled."
}
Protected token disabling
If the token is protected, you will receive this response. Remove the protected flag in a separate interaction before proceeding. This will also be an HTTP 403 error.
{
"ERROR": "Token is protected. Remove protected tag before deleting."
}
Token endpoint
You can modify the settings of an individual token by targeting that token in the path of your request. Authentication is the same as for root requests - header or QSP. A trailing slash is permitted but not required.
https://api.synopticdata.com/auth/v2/token/[a token value]
Currently only PATCH
HTTP methods are permitted against this endpoint - for the purpose of altering token settings with the attached payload.
PATCH request - modify settings
The payload of a PATCH request is used to alter the settings of the specified token. Payload follows this schema.
{
"tags":[
{
"name":"string",
"value":"any"
}
],
"request": {
"http_origins":[]
}
}
Tags
Including the tags key will entirely replace the tags set to the token. If omitted no changes are made to the tags on the token. If tags
is included but the list is empty, all tags are removed.
We restrict the tag values you can set. The only permitted tag name
values are:
protected
Request
If the request object is included, the request settings for the token are entirely replaced by those included in this interaction.
Only the following keys are supported in the request
object.
http_origins
which must be a list of valid URL’s
Example implementation
If you have an application where your client endpoints need their own Synoptic API tokens, you can use a central service controlled by you to invoke the credential API to generate tokens as desired, and then deliver that token to the client endpoint.
You may need to maintain your own inventory of issued tokens in order to remove the correct one in the future as needed to control access to your Synoptic API services.