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 (limited to 100)
Create new tokens
Disable tokens

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.

An Authentication request is an HTTP URL with the following form:

CODE

https://api.synopticdata.com/v2/auth

Acquiring data from this web service requires certain parameters. When encoding URLs, all parameters are separated using the ampersand (&) character and their value is indicated by an equal sign (=). Below is a list of accepted parameters.

apikey (required), Your private API key. All tokens created with this key will be associated with this key.

Optional Parameters

Only the private key used to generate a token can be used to perform actions on that token.

disableToken (token), Permanently deletes the token passed. This action is irrevocable.
list (1 | 0), returns a list of the tokens associated with the provided API key.
expire (string), YYYYmmddHHMM (UTC) timestamp when the newly created token should become disabled. After creation this time cannot be changed, and cannot be queried. Tokens will actually expire within 1 hour of this time.
cloneSettings (token), copy the settings from an existing token in your account to a new token. 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 Parameters

output (json [default] | xml), Indicates the response format of the request. It’s recommended to use the [JSON] format which there are well supported parsing libraries in all major languages.

Request Response

The Authentication service will return single organized and self describing JSON object. Each response is a slight bit different for each command executed against the API.

Create a token

/v2/auth?apikey=ABC123 or /v2/auth?apikey=ABC123&expire=123412010000 or /v2/auth?apikey=ABCD1234&cloneSettings=abcdef12345

JSON

{
  "TOKEN": "1672c91e97a7421f8ac67f7681d5810a"
}

List all tokens

Including the list argument with any value will change the behavior to give a list of tokens with the first and only JSON key. No tokens are created for these requests.

/v2/auth?apikey=ABC123&list=1

JSON

{
  "TOKENS": [
    "a6a82dddc14a46c892077bded6f5a342",
    "3839e26df2c54ae1aa064dc677ac1697",
    "0ca4be58420a43b3a27251ad9c376978",
    "1672c91e97a7421f8ac67f7681d58154"
  ]
}

Delete a token

/v2/auth?apikey=ABC123&disableToken=1672c91e97a7421f8ac67f7681d58142

JSON

{
  "MESSAGE": "Token 1672c91e97a7421f8ac67f7681d58142 is disabled."
}

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.