The Koordinates Token API is for creating and managing API tokens.

An API token enables users to access administration APIs, without needing to use a session token. An API token is identified with a 32 character key. You will only see the full key when the token is first created, so keep it safe and secure.

Token scopes

Tokens require specific scopes to use various APIs. For example, for a token to enable access to the documents API, it will need to have the following scopes:

• documents:read - View and query existing documents
  
• documents:write - Create and edit documents
  

The required scope for a view is provided in view headers Accepted-OAuth-Scopes. All requests authenticated via an OAuth2 key will include an OAuth-Scopes response header listing the token’s scopes.

Scope values follow the OAuth2 Access Token Scope RFC and are provided as a space-delimited list of scope strings.

Token referrer checks

Koordinates enables referrer checking, which you can use to restrict the use of administrative APIs in browser-based applications to specific domains. Each referrer check can be explicit (example.com or foo.example.com) or have a leading wildcard subdomain match (*.example.com).

If you enable referrer checks, Koordinates will inspect incoming requests, and reject any that do not match the specified rules.

However, please note that, while browsers will supply these values automatically, it is simple to create custom clients that supply arbitrary referrer headers. You should not rely on referrer checks to enforce token security.

For testing purposes, referrers with localhost will always be accepted:

• 127.0.0.1
  
• localhost
  
• ::1
  

Token List

Response 200

Returns a list of the authenticated user’s tokens. Note that full keys are never returned in GET requests. You will only see the key when it is first created.

Headers

Content-Type: application/json

[
    {
        "name": "Example Token 1", 
        "key_hint": "abc123...", 
        "url": "https://{domain}/services/api/v1/tokens/{id}/"
    }, 
    {
        "name": "Example Token 2", 
        "key_hint": "def456...", 
        "url": "https://{domain}/services/api/v1/tokens/{id}/"
    }
]

Creates a new API token. This uses OAuth2 password grant method.

Your request data must include the values:

• grant_type as password
  
• username (the authenticating users email address)
  
• password
  

You can also provide the requested scope, otherwise a set of default scopes will be assigned.

Other properties such as expires_at and referrers can be set at this point too.

Note that this follows the OAuth2 Resource Owner Password Credentials Grant specification.

application/x-www-form-urlencoded is supported but you can submit application/jsonbody if preferred.

No OAuth2 refresh token is supplied.

Content-Type: application/json

Body

{
    "name": "Example Token 3", 
    "expires_at": "2015-08-01T08:00:00.000Z",
    "scope": "query tiles catalog wxs:wfs wxs:wms wxs:wcs", 
    "referrers": [
        "*.example.com",
        "test.com"
    ]
}

Response 201

Headers

Content-Type: application/json

Body

{
    "name": "Example Token 3",
    "key": "850bd8372f5849adba6d7ad3df05624a",
    "key_hint": "850bd3...",
    "url": "https://{domain}/services/api/v1/tokens/{id}/",
    "created_at": "2015-06-24T09:31:18.779Z",
    "expires_at": "2015-08-01T08:00:00.000Z",
    "scope": "query tiles catalog wxs:wfs wxs:wms wxs:wcs",
    "referrers": [
        "*.example.com",
        "test.com"
    ]
}

Token detail

Response 200

Headers

Content-Type: application/json

Body

{
    "name": "Example Token 3",
    "key_hint": "850bd8...",
    "url": "https://{domain}/services/api/v1/tokens/{id}/",
    "created_at": "2015-06-24T09:31:18.779Z",
    "expires_at": "2015-08-01T08:00:00.000Z",
    "scope": "query tiles catalog wxs:wfs wxs:wms wxs:wcs",
    "referrers": [
        "*.example.com",
        "test.com"
    ]
}

Response 204