# OAuth

## Request token {#requestoauthtoken}

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](/docs/guides/wallet/api-security/#oauth-20) 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 ↓](#requestoauthtoken-examples)

### `POST /token`

**Security:**

- [basicOauth]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-basicOauth)

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Content-Type` | `string` | Required | The request must have a `Content-Type` of `application/x-www-form-urlencoded`. |

**Request body**

**Content-Type:** `application/x-www-form-urlencoded`

**One of:**

  - **`grant_type`** `string` **REQUIRED**

    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]({{< ref "/developer/rest-api/wallet/schemas/oauth/" >}}#oauthscope)>

    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](/docs/developer/rest-api/wallet/api-auth-reference/#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]({{< ref "/developer/rest-api/wallet/schemas/oauth/" >}}#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

  - **`assertion`** `object` <[Assertion JWT]({{< ref "/developer/rest-api/wallet/schemas/oauth/" >}}#assertionjwt)> **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](/docs/developer/rest-api/wallet/operations/oauth/#requestoauthtoken). The JWT must be signed with the private key corresponding to the `client_id` in the `kid` header using the ES384 algorithm.

  - **`grant_type`** `string` **REQUIRED**

    Possible values: `client_credentials`


**Responses**

**`200`** Returned on token request success.

Response headers:

| Name | Type | Description |
|------|------|-------------|
| `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`

- **`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]({{< ref "/developer/rest-api/wallet/schemas/oauth/" >}}#oauthscope)>

  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](/docs/developer/rest-api/wallet/api-auth-reference/#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`

- **`error`** `string` **REQUIRED**

  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:

| Name | Type | Description |
|------|------|-------------|
| `WWW-Authenticate` | `string` | The HTTP authentication methods that can be used to request an access token. |

Response body:

**Content-Type:** `application/json`

- **`error`** `string` **REQUIRED**

  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`

- **`error`** `string` **REQUIRED**

  Error code.

  Possible values: `invalid_request`

- **`error_description`** `string`

  A plain-text description of the error.

**Examples**

*Example request*

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

```

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

```

*Response*

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

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

```

---

## Verify public key {#getkeyverification}

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

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `kid` | `string` | Required | 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:

| Name | Type | Description |
|------|------|-------------|
| `Cache-Control` | `string` | The response contains a `Cache-Control` header which must be respected. |

Response body:

**Content-Type:** `application/x-pem-file`

Type: `string`

**`404`** The requested resource doesn't exist.

Response body:

**Content-Type:** `application/json`

Type: `object`

---