Cesium ion Access Tokens
Access tokens provide authentication when using Cesium ion’s REST API and are used to link API requests to your account. Access tokens allow you to integrate ion into your workflows and apps, including things like automating asset uploads and accessing your assets. This guide provides information about how to create and manage access tokens, and best practices to ensure account security.
You’ll learn how to:
- Create and manage tokens
- Configure your token for best security practices
- Track token usage
- A Cesium ion account
You can view, create, edit, and delete the access tokens for your account on the access tokens page of the ion dashboard. It’s best to create a unique access token for each application you develop. When you create a token, you can specify how the token can be used and what it can access. You’ll learn more about scopes, restricting app URLs, and selecting assets for the token further down in this guide.
Manage your tokens on the tokens page of the ion dashboard
Everything you can do with tokens in the ion dashboard can also be done with the Tokens REST API. Read the ion REST API documentation to learn more about the available endpoints.
Every account has a single default token with the public assets:read and geocode scopes. This token cannot be modified or deleted, and provides access to the ion geocoder and read access to all individual assets associated with your account. Using the default token is a convenient choice for development, but should not be used in production apps.
Scopes
A scope determines which parts of the ion API the token can use. These scopes are split into “public scopes”, scopes for tokens that are considered safe for use on public clients, and “private scopes”, scopes for tokens that should be kept secret because they provide potentially sensitive information or otherwise allow changes to be made to your account.
When choosing scopes, enable the minimum set of scopes needed to accomplish your particular task. For example, if you want to automate asset uploading, you should create a token that only has the assets:read and assets:write scopes. You should then create a token with just the assets:read scope for viewing the assets in an app.
Cesium ion has the following scopes:
Public Scopes
| Scope | Description |
|---|---|
assets:read | Read metadata and access the tiled data for individual assets in your account. |
geocode | Perform geocodes (for example, CesiumJS uses the ion geocode service by default for the search widget.) |
| Scope | Description |
|---|---|
assets:list | List the metadata for all assets available to your account. |
assets:write | Create, modify, and delete assets in your account. |
profile:read | Read your username, email address, avatar, and storage quota. |
tokens:read | Read token metadata and list all tokens for your account. |
tokens:write | Create, modify, and delete tokens for your account. |
Use the toggles to enable scopes when creating a token
URL Restrictions
By default, your access tokens can be used from anywhere and by anyone. You can make your token more secure by specifying one or more “Allowed URLs” from which the API request can originate. This is recommended for a token added to a public client to prevent your token from being used outside your app. This feature is only applicable to hosted web apps, and should not be set for tokens used in Cesium for Unreal.
Note that requests using a token with Allowed URLs must include a referer header. You may have to configure the referrer policy for your app to send this header with your requests.
URL Format
URLs must include
- A protocol (example: http or https)
- A domain (example: cesium.com)
And can optionally include
- A subdomain (example: sandcastle.cesium.com)
- A port (example: cesium.com:80)
- A path (example: cesium.com/cesiumjs/cesium-viewer/)
Matching Rules
URLs are matched based on the granularity you specify. If you only specify a protocol and domain, the token will allow requests from any subdomain and subpath on that domain, but if you specify a path, the token will allow requests only from that path and subpaths.
Examples:
https://cesium.comwill allow requests fromhttps://sandcastle.cesium.comhttps://cesium.comwill allow requests fromhttps://cesium.com/cesiumjs/cesium-viewer/https://cesium.com/cesiumjs/will allow requests fromhttps://cesium.com/cesiumjs/cesium-viewer/https://sandcastle.cesium.comwill not allow requestsfrom https://cesium.comhttps://cesium.comwill not allow requests fromhttp://cesium.comhttp://cesium.comwill not allow requests fromhttps://cesium.com
Choose the “Selected Urls” option to specify one or more allowed URLs
Asset Restrictions
Unless specified, access tokens with the assets:read scope can access all assets in your account. However, you can choose to restrict a token so it can only access a specific set of assets, preventing a malicious party from trying to find other assets you’ve uploaded. You can modify the list of assets at any time.
Choose the “Selected assets” option and select one or more assets
Restrict how your token can be used
When creating an access token, it should be configured so it has the minimal required access to ion in order for your app to work. This includes minimizing the set of enabled scopes and selected assets to only include the ones your app is using, and adding a URL restriction so the token only works on your domain.
Regenerate your default token
If you accidentally share your default token or otherwise think it is being used without your permission, you can regenerate it by clicking the ‘Regenerate’ button on the access tokens page in the ion dashboard. This will create a new default token and permanently revoke your previous one so apps using the old token will no longer be able to access the ion API.
Regenerate your default token using the button at the top of the right side panel
Rotating Tokens
It’s a good idea to occasionally rotate tokens that are used in public clients in the unlikely event that someone else decided to use your token in their app. To rotate a token, create a new token and add it to your app. Deploy the updated app, then revoke the old token after the updated app is live. You can also automate this process by leveraging the Tokens REST API. For example, you could create a new token and add it to your app as part of your release process.
Access tokens are used to track your account usage, including streaming, bing sessions, and geocodes. You can view both your total account usage and view usage per token on the usage page of the ion dashboard. Use the “Show usage for” drop down above the tables to select a particular token. Tracking usage is helpful to determine which of your applications is getting the most use, or if there’s an unexpected surge in usage from one of your tokens. Learn more about usage in our Optimizing Quotas guide.
The usage page on the ion dashboard shows your usage over time
When should and shouldn’t I use the default access token?
Your default access token can be used for local development purposes, but should be replaced with a new token when your app is ready for production.
If I open the quick sandcastle link, does it generate a new access token?
The sandcastle examples opened from ion use your account’s default token.
Should I create an access token per application?
Yes, it is best to create a new access token for each of your applications.
Should I create a new access token for each asset?
This is probably not necessary. Instead, create one token per application and configure the token to have access to all of the assets used in that application.
How do I fix “Warning, This application is using Cesium’s default ion access token”?
For trying out our library, CesiumJS releases include a demo access token that only has access to a handful of assets. All users are required to replace this with an access token from their own ion account once they begin development.
Do access tokens have an expiration date?
No, access tokens will continue to work until you revoke them.
How do I manage access tokens with the REST API?
See our ion REST API documentation to see available endpoints for adding, editing, and deleting access tokens using the REST API.
Which asset token is used in my Cesium Stories?
Each of your Cesium Stories uses its own story-specific token that only has access to the assets added to the story.
How do I change the access token used in my Cesium Stories?
This is not configurable at this time.
Need more help? Visit the Cesium Community Forums to ask a question or view answers.