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 Private 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.synopticdata.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

• Create a new token with specified settings

• List available tokens

• Disable a token

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)

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.

Providing both parameters will result in listall behavior. Cannot be combined with expire, cloneSettings, or disableToken parameters (400 error).

Response format

Basic list

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

Always a list of strings under the TOKEN key.

{
  "TOKENS": [
    "cb39d7c75d3e45b1b98d3bf118831b98",
    "52f74218e9d54f739adca46154ebcf80",
    "f59b66e3c0814037ac610124ade2b11a"
  ]
}

List all

/auth/v2/?apikey=ABC123&listall or /auth/v2/?apikey=ABC123&listall=1

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 of name, value pairs representing the keys associated with the token. Note the special effect of the protected tag below.

• expire - a timestamp for the expire time set when the token was created.

Not all settings are displayed.

{
    "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.

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 learn more

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 URLs following the convention documented in the token settings request documentation

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.

Deprecated URLs

The following URLs have been supported in the past, and should be changed to the URL indicated in the documentation. We may terminate support for any of these endpoints with limited notice.

https://api.synopticdata.com/v2/auth (note the reversal of auth and v2)

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