Public API Tokens

Public API Tokens are short alpha-numeric strings used to identify the account requesting data through our web services. Tokens are different from API Keys.

How do I use my tokens?

Whenever you ask for data from one of our services, you will give us your token to identify youtself either as a URL parameter or part of the URL path itself. Use only one token per request, and consult the documentation for the data service you are using to know how best to include the token.

Here are some examples of how a token may be included in a data request:

• As a query string argument to a service

  CODE

    https://api.synopticdata.com/v2/stations/metadata?token={my public token}&stid=KONT&complete=1

• As a part of the path for certain services (this is less common)

  CODE

    wss://push.synopticdata.com/feed/{my public token}/?state=ca&vars=air_temp,wind_speed

• As an Authorization header Bearer value - this is also less common

  CODE

    Authorization: Bearer {your public token}

You should not use a new token for every API request

How do I manage my tokens?

If you wish to create, view, or disable your API tokens, you have two options:

• Through your Manage Tokens tab on your credentials control panel

• Using your private API key which was created when you opened your developer account.

When should I use multiple tokens?

You are always free to have multiple tokens, but there is never a requirement to use them. Tokens are a way of separating and controlling your own API usage. If you are using your Synoptic data access individually, or purely internally for processes, it is likely not necessary for you to use multiple tokens.

However, if your use of our data services may be accessible to others, such as on a webpage your customers visit, you may want to use multiple tokens to isolate each application or user, and give you more control over your API usage.

Token appearance

Tokens consist of different characters, and are a different length from API keys. Tokens you generate from your developer account (either with your API key or in your control panel) will be 32 characters long, with only hexadecimal characters (0-9 and a-f). A key, alternatively will use a much more diverse array of letters as well as numbers.

Here is an example token

46a4eccec1414feab118287faafc5c80

Settings

By default, tokens will enable all of the features and capabilities of your Synoptic account when interacting with a service. However we are also able to assign custom settings to a token which will reduce the features a certain token can use.

An example of this is where your Synoptic account may have access to restricted mesonet station data. However, let’s say you would like to make an application which shares data publicly. As part of your access agreement for certain data, you cannot share it publicly. Thus, you can use a token with settings which prevent the restricted data from displaying in applications which use it downstream.

You cannot set token settings directly. If you have a use case for a token which has restricted functionality, contact us and we can work with you to define this.

New tokens with matching settings can be generated immediately via the /auth api endpoints once it has been assigned (e.g. for token rotation) using the cloneSettings argument. Learn more

Details about tokens

• When created with your API key, tokens are valid indefinitely.

• When you disable your API key or close your Synoptic account, all of your API tokens will be automatically disabled. Replacing your existing API key with a new key will also disable all existing tokens associated with the previous key.

• We do not currently restrict how many tokens can be associated with a given API key.

• You cannot have any influence on the string characters of a token.

• We select your earliest-created, active token as your “default” token, which only means is the one presented front-and-center on your credentials control panel.

• There are over a septillion (10²⁴, a trillion trillion) possible token values, so you will never have to share, and probably won’t be able to guess one.