Token Settings

By default, tokens will enable all of the features and capabilities of your Synoptic account when interacting with a service. Tokens can individually be modified to work differently. This guide outlines several ways tokens can be adjusted.

There are two kinds of token settings - user editable and protected. New tokens with matching settings (protected and user editable) can be generated immediately via the /auth credential API service once it has been assigned (e.g. for token rotation) using the cloneSettings argument. Learn more

Token settings only affect the token they are set on, and do not alter the access of your account or any other tokens.

User-editable settings

The customer console or Credential API can be used to set, edit and delete these settings at any time. These settings will affect how the token can be used, but will not influence the data or services available to the token holder’s account.

Tags

Tokens may have tags, which are used for token management. See the tags settings API docs to learn about available tags and how to modify them. Certain tags will influence the function of other administrative functions (such as preventing token disabling when a protected tag is defined)

Protected tag

You have the ability to define a tag with the name protected for any token. This tag, when present, a request to disable the token will reject with a 400 error.

Request settings

These settings manage whether a certain HTTP interaction is permitted. If a request setting is established, the token may only be used where the indicated criteria is satisfied.

An example use is to restrict a token to being used within a web application available at a specific domain (origin). When defined, the token will be usable when used within the application, and will not be usable elsewhere. This reduces the challenges associated with publicly sharing tokens, as is required in public web applications. When setting an origin restriction, note that you will need to use a different token, without request origin settings, to perform requests from backend processes.

Supported request criteria

The following parameters of a request may be limited.

HTTP Origin

Defining one or more HTTP Origin header values in the request settings instructs our services to reject (HTTP 403 - unauthorized error) any request using that token except where it comes with an HTTP Origin header that complies with the following convention:

For any listed origin (domain) of the form [protocol]://[domain] the protocol must match, and the domain must be an exact match of the listed domains (e.g. subdomains are not automatically approved).

A wildcard character (*) can be used to support any subdomain at or below that level. You may also use wildcards to specify ports (following a colon). You cannot use wildcards to the right of a domain name.

Valid origin examples

(the following examples exclude protocol for brevity, protocols must match)

Private settings

These are generally not visible to you or anyone else, and will affect the data access and performance of the token. Because they can alter your contracted access, these modifications must be made by contacting synoptic and requesting a change.

Limit restricted data available to a token

For customers who have access to restricted data, a token can be made to only access public data for use in public or uncontrolled applications. This allows you to confidently avoid exceeding distribution agreements when using our services to power your tools.

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.