Skip to main content
Skip table of contents

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.

CODE
https://api.synopicata.com/auth/v2/

To manage token settings (not including creating or deleting tokens) use a URL of the following format

CODE
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.

CODE
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

CODE
/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.

expire

YYYYmmddHHMM (UTC)

/?expire=202312312359

a timestamp after which the token you are creating will no longer be valid. This value cannot be edited later.

cloneSettings

/?cloneSettings=abcd1234...

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:

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

list

1 or 0, can be included without value

&list

Return a basic list of token values

listall

1 or 0, can be included without value

&listall

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

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

/auth/v2/?apikey=ABC123&listall
CODE
{
    "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

disableToken

full token value to disable

&list

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

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

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

CODE
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.

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.