Cesium Tokens API

openapi: 3.2.0
info:
  title: Cesium ion Tokens API
  version: v1
  description: '# Overview


    The Cesium ion REST API allows you to leverage ion''s powerful tiling and streaming capabilities from your own applications and workflows.'
servers:
- url: https://api.cesium.com
  description: Cesium ion API Server
security:
- OAuth2: []
tags:
- name: Tokens
  description: 'The Tokens API provides a mechanism to create and manage access tokens. Access tokens are used to give applications access to your ion account, including access to stream your ion assets.


    Every account has a single default token with the `assets:read` and `geocode` scopes. This token cannot be modified or deleted, and provides read access to all assets associated with that user''s ion account.'
paths:
  /v2/tokens:
    get:
      operationId: getTokens
      summary: List tokens
      description: 'Retrieves all available tokens, splitting the result across multiple requests using pagination.


        After receiving the initial page of tokens, you can request the next and previous pages using the RFC 5988 formatted strings contained in the `Link` header with the `next` and `prev` relations. The process of fetching the next page of tokens can be repeated until the client receives a response with no link header or no `next` relation in the link header, which means all tokens have been returned. The link urls should be treated as an opaque link as the actual format may change at any time.'
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:read
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          default: 1000
          example: 50
          minimum: 1
          maximum: 1000
        description: The maximum numbers of tokens to return. Receiving fewer tokens should not be interpreted as the end of the collection. The end of the collection is reached when the response does not contain a link header.
      - in: query
        name: page
        schema:
          type: integer
          default: 1
          minimum: 1
          example: 3
        description: The page number.
      - in: query
        name: search
        schema:
          type: string
          example: roads
        description: One or more keywords separated by whitespace by which to filter the list of tokens.  The token name will contain each keyword of the search string.
      - in: query
        name: sortBy
        schema:
          type: string
          example: NAME
          enum:
          - NAME
          - LAST_USED
        description: The property by which to sort the results.
      - in: query
        name: sortOrder
        schema:
          type: string
          default: ASC
          example: ASC
          enum:
          - ASC
          - DESC
        description: The order in which to sort the results.  If undefined, tokens are sorted ascending.
      responses:
        200:
          description: OK
          headers:
            link:
              $ref: '#/components/headers/link-next-prev'
          content:
            application/json:
              schema:
                title: Token Metadata
                type: object
                properties:
                  items:
                    type: array
                    description: A page of tokens.
                    items:
                      $ref: '#/components/schemas/TokenMetadata'
              examples:
                exampleResponse:
                  value:
                    items:
                    - id: 58d917ab-f5df-494c-9109-66be3c53219d
                      name: An Access Token
                      token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtOTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ96fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM
                      isDefault: false
                      dateLastUsed: '2021-10-18T15:55:43.977Z'
                      dateAdded: '2021-09-10T18:29:57.583Z'
                      dateModified: '2021-09-11T18:29:57.583Z'
                      scopes:
                      - assets:list
                      - assets:read
                      - assets:write
                      - geocode
                      - profile:read
                      assetIds: []
                    - id: 8494d9bc-a0c7-46ac-b0f5-58bdd6a9724a
                      name: Another New Token
                      token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI4NDk0ZDliYy1hMGM3LTQ2YWMtYjBmNS01OGJkZDZhOTcyNGEiLCJpZCI6MiwiaWF0IjoxNjMzOTgyNjk5fQ.JcD0nmNbO-vVQsoa5w8CudbsCeuN1d7Svmy_GzoehHg
                      isDefault: false
                      dateLastUsed: '2021-10-11T20:04:59.380Z'
                      dateAdded: '2021-09-09T18:29:57.583Z'
                      dateModified: '2021-09-10T18:29:57.583Z'
                      scopes:
                      - assets:read
                      - geocode
                      assetIds:
                      - 80
                      - 98
        401:
          $ref: '#/components/responses/401'
    post:
      operationId: postTokens
      summary: Create a new token
      description: Add a new token which can be used for making ion API requests.
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/TokenName'
                assetIds:
                  $ref: '#/components/schemas/TokenAssetIds'
                scopes:
                  $ref: '#/components/schemas/TokenScopes'
                allowedUrls:
                  $ref: '#/components/schemas/TokenAllowedUrls'
              required:
              - scopes
            examples:
              exampleBody:
                value:
                  name: Token
                  scopes:
                  - assets:read
                  - geocode
                  - profile:read
                  assetIds:
                  - 98
                  - 96
                  - 94
                  - 89
                  allowedUrls:
                  - https://example.com
                  - https://subdomain.example.com
                  - https://example.com/path/
                  - https://example.com:8080
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadata'
              examples:
                exampleResponse:
                  value:
                    id: 3171672f-b6a3-43ae-90d5-0d559a7bf73b
                    name: Token
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIzMTcxNjcyZi1iNmEzLTQzYWUtOTBkNS0wZDU1OWE3YmY3M2IiLCJpZCI6MSwiaWF0IjoxNjM0Njc1OTU0fQ.cRbNs2IKXbvZjVpjWIId3YB3CeppiIQgbR7mZTKC1UI
                    isDefault: false
                    dateLastUsed: '2021-10-19T20:39:14.372Z'
                    dateAdded: '2021-10-19T20:39:14.372Z'
                    dateModified: '2021-10-19T20:39:14.372Z'
                    scopes:
                    - assets:read
                    - geocode
                    - profile:read
                    assetIds:
                    - 98
                    - 96
                    - 94
                    - 89
        409:
          description: Invalid Request
  /v2/tokens/{tokenId}:
    parameters:
    - $ref: '#/components/parameters/tokenId'
    get:
      operationId: getToken
      summary: Get info about a token
      description: Retrieves metadata for a specific token.
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:read
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadata'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
    patch:
      operationId: patchToken
      summary: Modify token info
      description: 'Updates the name, scopes, asset ids, allowed URLs, or expiration associated with the token.


        `assetIds`, `allowedUrls`, and `expiration` are signed into the token itself. Setting any of them to a value different from what the token currently has always regenerates the token''s credentials, even if `regenerate` is not set: the previous encoded token stops working immediately, and the response contains the new one. `regenerate` can also be set on its own to force new credentials without changing anything else.'
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/TokenName'
                assetIds:
                  $ref: '#/components/schemas/PatchTokenAssetIds'
                scopes:
                  $ref: '#/components/schemas/TokenScopes'
                allowedUrls:
                  $ref: '#/components/schemas/PatchTokenAllowedUrls'
                expiration:
                  description: The date and time after which the token is no longer valid, in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. Pass `null` to remove the expiration. Changing this value regenerates the token's credentials (see above).
                  type:
                  - string
                  - 'null'
                  format: date-time
                  example: '2027-03-19T13:17:02.838Z'
                regenerate:
                  description: If true, replaces the token's credentials with newly generated ones, invalidating the previous encoded token, even if no other field is changing.
                  type: boolean
                  example: false
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadata'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
    delete:
      operationId: deleteToken
      summary: Delete a token
      description: Deletes a token. Does not support deleting the default token.
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:write
      responses:
        204:
          description: No Content
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
  /v2/tokens/default:
    get:
      operationId: getDefaultToken
      summary: Get the default token
      description: Retrieves metadata for the user's default token.
      tags:
      - Tokens
      security:
      - AccessToken:
        - tokens:read
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadataDefaultToken'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
components:
  schemas:
    AssetIdentifier:
      type: integer
      description: The unique identifier for this asset.
      example: 3812
    TokenAllowedUrls:
      description: The URLs from which this token can be accessed. If undefined, the token can be accessed from any URL.
      type: array
      example:
      - https://example.com
      - https://subdomain.example.com
      - https://example.com/path/
      - https://example.com:8080
    TokenAssetIds:
      description: The ids of the assets that can be accessed using this token.  If undefined, the token can access all assets associated with the account.
      type: array
      items:
        $ref: '#/components/schemas/AssetIdentifier'
      example:
      - 90
      - 98
      - 99
      - 100
    TokenName:
      type: string
      description: The name of this token.
      example: New Token
    TokenMetadata:
      title: Token Metadata
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TokenIdentifier'
        name:
          $ref: '#/components/schemas/TokenName'
        token:
          $ref: '#/components/schemas/Token'
        dateAdded:
          description: The date and time that this token was created in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        dateModified:
          description: The date and time that this token was last modified in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        dateLastUsed:
          description: The date and time that this token was last used in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        assetIds:
          $ref: '#/components/schemas/TokenAssetIds'
        isDefault:
          description: True if this token is the default token, else false.
          type: boolean
          example: false
          readOnly: true
        allowedUrls:
          $ref: '#/components/schemas/TokenAllowedUrls'
        scopes:
          $ref: '#/components/schemas/TokenScopes'
        expiration:
          $ref: '#/components/schemas/TokenExpiration'
      required:
      - scopes
    TokenScopes:
      type: array
      items:
        type: string
        enum:
        - assets:list
        - assets:limited-list
        - assets:read
        - assets:write
        - geocode
        - profile:read
        - labels:read
        - labels:write
        - tokens:read
        - tokens:write
      description: 'Defines the [scope](#tag/Authentication) of this particular token.

        '
      example:
      - profile:read
    TokenIdentifier:
      type: string
      description: The unique identifier of this token.
      example: a4538dc7-f583-4d9e-889e-35e2db4de534
      readOnly: true
    Token:
      type: string
      description: The access token.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ6fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM
    PatchTokenAllowedUrls:
      description: The URLs from which this token can be accessed. Set to `null` if you want your token to be accessed from any URL.
      type: array
      example:
      - https://example.com
      - https://subdomain.example.com
      - https://example.com/path/
      - https://example.com:8080
    TokenMetadataDefaultToken:
      title: Token Metadata
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TokenIdentifier'
        name:
          $ref: '#/components/schemas/TokenName'
        token:
          $ref: '#/components/schemas/Token'
        dateAdded:
          description: The date and time that this token was created in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        dateModified:
          description: The date and time that this token was last modified in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        dateLastUsed:
          description: The date and time that this token was last used in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
          type: string
          format: date-time
          example: '2019-03-19T13:17:02.838Z'
          readOnly: true
        assetIds:
          $ref: '#/components/schemas/TokenAssetIds'
        isDefault:
          description: True if this token is the default token, else false.
          type: boolean
          example: true
          readOnly: true
        scopes:
          $ref: '#/components/schemas/TokenScopes'
      required:
      - scopes
    PatchTokenAssetIds:
      description: The ids of the assets that can be accessed using this token.  Set to `null` if you want your token to access all of your assets.
      type: array
      items:
        $ref: '#/components/schemas/AssetIdentifier'
      example:
      - 90
      - 98
      - 99
      - 100
    TokenExpiration:
      description: The date and time after which the token is no longer valid, in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.  Not present if the token never expires.
      type: string
      format: date-time
      example: '2027-03-19T13:17:02.838Z'
  parameters:
    tokenId:
      description: The unique identifier of the token on which to perform the operation.
      in: path
      name: tokenId
      schema:
        $ref: '#/components/schemas/TokenIdentifier'
      required: true
  headers:
    link-next-prev:
      schema:
        type: string
        description: 'An [RFC 5988](https://tools.ietf.org/html/rfc5988) formatted string with a relation type of `next` which points to the next page of data on the server, if it exists, and a relation type of `prev` which points to the previous page of data on the server, if it exists. This url should be treated as an opaque link as the actual format may change at any time.

          '
  securitySchemes:
    OAuth2:
      description: 'All Cesium ion endpoints require authentication in the form of an access token provided in the `Authorization` header of the request. ion uses the OAuth 2.0 `Bearer <your_access_token>` format.

        '
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cesium.com/ion/oauth/
          tokenUrl: https://api.cesium.com/oauth/tokens
          scopes:
            assets:list: List the metadata for all assets available to the account.
            assets:limited-list: List the metadata for selected assets available to the account.
            assets:read: Read metadata and access the tiled data for individual assets available to the account.
            assets:write: Create, modify, and delete assets in the account.
            labels:read: List labels in the account.
            labels:write: Create, modify, and delete labels in the account.
            geocode: Enables the CesiumJS geocoder. Note geocoding via the REST API is not yet supported.
            profile:read: Read your username, email address, avatar, and storage quota.
            archives:read: List and download asset archives.
            archives:write: Create and delete asset archives.
            exports:read: List asset exports.
            exports:write: Export assets.
            tokens:read: Read token metadata and list all tokens for the account.
    AccessToken:
      description: 'A Cesium ion access token provided as a Bearer token in the `Authorization` header. An access token can be

        used anywhere an OAuth 2.0 token can, with the same scopes, and additionally supports the `tokens:write`

        scope, which is not available via OAuth 2.0 since granting a third-party OAuth client the ability to

        create, modify, and delete a user''s other tokens is out of scope for delegated access.

        '
      type: http
      scheme: bearer