OAuth

Request token

Request an OAuth access token with Basic Auth or an assertion. When making a request with an assertion, do not provide the Basic Auth header. See also OAuth 2.0 in the Wallet API Security documentation.

Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when requesting an OAuth token.

Jump to examples ↓

POST /token

Security:

basicOauth

Request headers:

Content-Type stringREQUIRED
The request must have a Content-Type of application/x-www-form-urlencoded.

Request body:

Content-Type: application/x-www-form-urlencoded
One of
- Request token with Basic Auth object
  OBJECT PROPERTIES
  - grant_type stringREQUIRED
    Possible values:
    - client_credentials
  - ipaddr string
    A list of CIDR representations of valid IP addresses to which the issued token is restricted. IP addresses can be sent as a URL-encoded, space-delimited list (example: ipaddr=24.20.40.0%2F24%202001%3A4860%3A4860%3A%3A8888%2F32) or as a list as expected in a query parameter form (example: ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32).
  - scope string<OAuth Scope>
    A list of scopes to which the issued token will be entitled. Scopes can be sent as URL-encoded, space-delimited list (example: scope=wpas%20wtmp) or as a list as expected in a query parameter form (example: scope=wpas&scope=wtmp).
    The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope. For more information about scope values, see OAuth token scopes in the Wallet API Authorization Reference documentation.
    - wadl: Adaptive Links
    - wevt: Events
    - wfli: Flights
    - wnot: Notifications
    - wpas: Passes
    - wprj: Projects
    - wsch: Schedules
    - wseg: Segments
    - wrpt: Statistics
    - wtmp: Templates
    Possible values:
    - wadl
    - wevt
    - wfli
    - wnot
    - wpas
    - wprj
    - wsch
    - wseg
    - wrpt
    - wtmp
  - sub object<Subject>REQUIRED
    A space-delimited set of identifiers for which subjects a token is allowed. An app subject is required. Example: app:JQIMcndxIHWy2QISpt1SpZ.
    A space-delimited set of identifiers for which subjects a token is allowed. Example: app:JQIMcndxIHWy2QISpt1SpZ
    - app: May operate on the given app
- Request token with assertion object
  OBJECT PROPERTIES
  - assertion object<Assertion JWT>REQUIRED
    An encoded JWT that contains the required headers and claims and is signed with the client credentials’ private key.
    A JSON Web Token (JWT) used for authorization in OAuth token requests. The JWT must be signed with the private key corresponding to the client_id in the kid header using the ES384 algorithm.
  - grant_type stringREQUIRED
    Possible values:
    - client_credentials

Responses

200
Returned on token request success.
Response headers:
- Cache-Control string
  Possible values:
  - no-store
- Content-Type string
  Possible values:
  - application/json
- Pragma string
  Possible values:
  - no-cache
Response body:
- Content-Type: application/json
  Issued access token.
  OBJECT PROPERTIES
  - access_token string
    The issued token that can be used for all endpoints as allowed by set scopes.
  - expires_in integer
    The number of seconds from the time the token is generated until it expires.
  - scope string<OAuth Scope>
    A space-delimited list of scopes of the issued token. There may be undocumented scopes in this list.
    The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope. For more information about scope values, see OAuth token scopes in the Wallet API Authorization Reference documentation.
    - wadl: Adaptive Links
    - wevt: Events
    - wfli: Flights
    - wnot: Notifications
    - wpas: Passes
    - wprj: Projects
    - wsch: Schedules
    - wseg: Segments
    - wrpt: Statistics
    - wtmp: Templates
    Possible values:
    - wadl
    - wevt
    - wfli
    - wnot
    - wpas
    - wprj
    - wsch
    - wseg
    - wrpt
    - wtmp
  - token_type string
    The type of issued token.
    Possible values:
    - Bearer
400
Token not generated.
Response body:
- Content-Type: application/json
  Token request error.
  OBJECT PROPERTIES
  - error stringREQUIRED
    Error code.
    Possible values:
    - invalid_scope
    - invalid_request
    - invalid_grant
    - unauthorized_client
    - unsupported_grant_type
    - invalid_client
  - error_description string
    A plain-text description of the error.
401
Unauthorized.
Response headers:
- WWW-Authenticate string
  The HTTP authentication methods that can be used to request an access token.
Response body:
- Content-Type: application/json
  Authentication via the Authorization request header failed.
  OBJECT PROPERTIES
  - error stringREQUIRED
    Error code.
    Possible values:
    - invalid_client
  - error_description string
    A plain-text description of the error.
406
Not acceptable.
Response body:
- Content-Type: application/json
  Unsupported Accept header. The request only supports application/json, application/x-www-form-urlencoded, text/plain.
  OBJECT PROPERTIES
  - error stringREQUIRED
    Error code.
    Possible values:
    - invalid_request
  - error_description string
    A plain-text description of the error.

Examples

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Authorization: Basic <Base64 client_id:client_secret>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=wtmp%20wprj&sub=app:<project_id>

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Authorization: Basic <Base64 client_id:client_secret>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=assertion&assertion=<ES384 encoded JWT>

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

{
  "access_token": "...",
  "expires_in": 3600,
  "scope": "wtmp wprj",
  "token_type": "Bearer"
}

Verify public key

Retrieve the public key of a key ID. Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when verifying an OAuth public key.

GET /verify/public_key/{kid}

Path parameters:

kid stringREQUIRED
The private key ID used to sign the token. Example: 8817e96

Responses

200
Returned on success with the public key for the given kid.
Response headers:
- Cache-Control string
  The response contains a Cache-Control header which must be respected.
Response body:
- Content-Type: application/x-pem-file
  Type: string
  The PEM-formatted public key.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/json
  Type: object
  The error includes as much information as possible to help you understand the reason for the failure.