Table Of Contents

Previous topic

Token Server

Next topic

User Flow

This Page

Token Server API v1.0

Note

Unless stated otherwise, all APIs are using application/json for the requests and responses content types.

GET /1.0/<app_name>/<app_version>

Asks for new token given some credentials in the Authorization header.

By default, the authentication scheme is Browser ID but other schemes can potentially be used if supported by the login server.

  • app_name is the name of the application to access, like sync.
  • app_version is the specific version number of the api that you want to access.

The first /1.0/ in the URL defines the version of the Sagrada token.

Example for Browser-Id:

GET /1.0/sync/2.0
Host: token.services.mozilla.com
Authorization: Browser-ID <assertion>

This API returns several values in a json mapping:

  • id – a signed authorization token, containing the user’s id for the application and the node.
  • key – a secret derived from the shared secret
  • uid – the user id for this service
  • api_endpoint – the root URL for the user for the service.
  • duration – the validity duration of the issued token

Example:

HTTP/1.1 200 OK
Content-Type: application/json

{'id': <token>,
 'key': <derived-secret>,
 'uid': 12345,
 'api_endpoint': 'https://example.com/app/1.0/users/12345',
 'duration': 300,
}

Conditions to use the service

If the service needs the user to accept some terms of service, privacy policy, etc, the client needs to send a special flag saying that these terms of service had been effectively signed. Here is the intended client/server flow:

On the first call, the URLs that the user has to agree on are not known by the client. The server will answer with a HTTP 403 “Need to accept conditions” containing a json dict with the conditions that need to be accepted. This can be something like:

> GET /1.0/aitc/1.0
  Authorization: Browser-ID <assertion>

< 403 Forbidden
  Content-Type: application/json

  { 'status': 'error',
     'errors': [{'location': 'header',
                 'name': 'X-Conditions-Accepted',
                 'description': 'Need to Accept conditions'},
                 'condition_urls': {'tos': 'http://url-to-tos'}],
  }

On the next call, the client needs to include the ‘X-Conditions-Accepted’ HTTP header to indicate acceptance of the terms:

> GET /1.0/aitc/1.0
  Authorization: Browser-ID <assertion>
  X-Conditions-Accepted: True

< HTTP/1.1 200 OK
  Content-Type: application/json

  { ... token details ... }

Errors

All errors are also returned as json responses, following the structure described in Cornice

Status codes and error codes:

  • 404 : unknown URL, or unsupported application.
  • 400 : malformed request. Possible reasons:
  • missing option
  • bad values
  • malformed json
  • 401 : authentication failed or protocol not supported. The response in that case will contain WWW-Authenticate headers (one per supported scheme)
  • 405 : unsupported method
  • 406 : unacceptable - the client asked for an Accept we don’t support
  • 503 : service unavailable (ldap or snode backends may be down)