get started!
SynopticLabs APIs Guides

Authentication & Tokens

While our APIs serve public needs and information, we want to be aware of who is using our APIs, and how. Our API web services use a very simple public token authentication procedure: you just give us a string token as an argument every time you request something from an API. A token is associated with the API key and account that was used to generate it. When you use a token you own, we record that API request as yours. All API queries must be made with a public token.

Generating tokens

As discussed in the Keys guide, your private API key is used to generate, list, and disable your public API tokens. You must keep the process that generates tokens, and the key used, separate from your apps. For testing, feel free to start with the demotoken API token.

A usage example for your API key is an app which serves data from our API to registered users. When a user registers, on your servers you would create an API token for that specific user, then let their app instance have and use that token to directly query our APIs.

Authenticate using tokens

There are two forms our APIs may use to accept an authentication token:

  1. a &token= query string parameter is required by a resource. An example of this is a Mesonet API query for station metadata:{a public token}
  2. The token is a component in the resource address. For instance, a resource for a certain API may be structured like this{a public token}/realtime

Which method a particular API uses is outlined in its documentation.

We never use private keys for API authentication, because the token use for authentication is often visible to the users of your application.

More details about tokens

  1. All tokens technically expire 10 years from their creation date.