OAuth

Request an OAuth 2.0 token using Basic Auth or an assertion.

Key verification

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 when verifying an OAuth public key.

Jump to examples ↓

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.

Examples

GET /verify/public_key/8817e96 HTTP/1.1
Host: oauth2.asnapius.com
Accept: text/plain

HTTP/1.1 200 OK
Content-Type: application/x-pem-file
Cache-Control: max-age=600, must-revalidate

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE7tcTz03ypC7PSPa73Cbgl7AbDDo+92eH
DWgjAi6vt1gmlHE35e+GhpcwbywBByOiooY+5bvfUHkc0aKy4R8VbBK0rYwlp8B+
fxyDr9Ye/oiUewMwwlp0z5AMPjgBUIKS
-----END PUBLIC KEY-----

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PublicKeyVerificationRequest request = PublicKeyVerificationRequest.newRequest("<kid>");
Response<String> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

public_key = oauth.verify_public_key('<key_id>')

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 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

Note

When using the OAuth token for Airship API endpoints, make sure your requests are using the appropriate domain.

This example uses the OAuth token to list channels on Airship’s North American cloud site:

 curl --location 'https://api.asnapius.com/api/channels/' \
 --header 'Accept: application/vnd.urbanairship+json; version=3;' \
 --header 'Authorization: Bearer {OAUTH_ACCESS_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 object<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=chn%20nu) or as a list as expected in a query parameter form (example: scope=chn&scope=nu).
    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.
    - att: Attachments
    - chn: Channels
    - evt: Events
    - lst: Lists
    - nu: Named Users
    - pln: Pipelines
    - psh: Push
    - sch: Schedules
  - 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 object<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.
    - att: Attachments
    - chn: Channels
    - evt: Events
    - lst: Lists
    - nu: Named Users
    - pln: Pipelines
    - psh: Push
    - sch: Schedules
  - 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
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic <base64 encoded string of "client_id:client_secret">

grant_type=client_credentials&sub=app:JQIMcndxIHWy2QISpt1SpZ&scope=chn&scope=nu&ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setClientSecret("<client_secret>")
        .setSub("<sub>")
        .setScopes(Arrays.asList("<scope1>","<scope2>","<...>"))
        .setIpAddresses(Arrays.asList("<IP1>","<IP2>",<...>))
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("yourAppKey")
        .setOAuthCredentials(oAuthCredentials)
        .build();

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&assertion=<encoded_jwt>

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setAssertionJWT("<encoded_jwt>")
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setOAuthCredentials(oAuthCredentials)
        .build();

# The python OAuth client handles JWT creation 
# and token refresh automatically.
# Once instantiated, this can be used as any other Airship client.

airship_client = OAuthClient(
  client_id="<client_id>",
  private_key="<private_key>",
  key="<project_key>",
  scope=["<scopes>",],
  id_addr=["<ip list>",],
  timeout="<timeout seconds int>",
  retries="<attempts on failure int>"
)

require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

airship = UA::Client.new(key: app_key, oauth: oauth)