# Introduction


The Wallet API provides programmatic access to Airship Wallet service,
where you can create passes for Apple Wallet and Google Wallet. Passes are:

* Created from templates within a project. The project determines the types of templates and passes you create; your templates determine the style and default data for your passes.
* Distributed as links—When creating a pass or an adaptive link, you are creating a link. Users tap this link (or scan a QR code representing the link, etc.) to install the pass on their device.
* Customizable—Add relevant data to your users when they install your pass.
* Updatable with relevant field and value changes. After users install your passes, you can update passes with relevant field and values so your users' passes are always up to date.


For a better understanding of Airship Wallet projects and passes, see [How mobile wallet works](/docs/guides/wallet/getting-started/how-mobile-wallet-works/).

See the [Getting Started Guide](/docs/guides/wallet/getting-started/wallet/) for help setting up an Airship Wallet project.

## API Request Format

All API requests are HTTP requests. For all requests with a body, the body may be in [JSON](https://www.json.org/json-en.html)
format or other formats like CSV as specified for the endpoint. The proper Content-Type for
JSON is `application/json` and the proper content type for CSV is `text/csv`.

## Date/Time Format

All date/time values are represented according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) in UTC.
A `T` separator is preferred but not required. It will be included in all date/time values generated by the API.

Example: `2023-01-28T15:00-05:00`

## Security {#intro-security}

* Our APIs only work under 2048-bit HTTPS encrypted connections to ensure your data is private from client to server connections.
* Access is authenticated through a unique secret API key which we provide to you in your Wallet dashboard. It is your responsibility to keep this key well-guarded, as it represents your identity.
* You will use your own Apple Pass Type Certificate or Google Pay certificate to sign production passes. 

## Specifying a version

  The current version of the Wallet API is 1.2. The versioning for the Wallet API is currently distinct from the versioning for the Airship Engage API.


  Always specify the version of the API you want to use by adding an HTTP header called
   `Api-Revision`. The value of that header should be in the format x.y where x is the API version and y the sub-revision. For instance, 1.2 is for the /v1 API, revision 2.


## External IDs

Most endpoints support an `externalId` parameter in the path. While all assets
within this API typically have an internal `id`, you can use the `externalId` parameter to grant custom identifiers to your assets — projects, templates, passes, etc. These identifiers can make your assets more recognizable and help you integrate with an external application or system.


If you want to use external IDs, you should use them for all assets — projects, templates, passes, etc.


In general you can support external IDs by appending `/id/{externalId}` to an endpoint path that would either take or generate a standard `id`.

## Base URL {#servers}

Select the domain associated with your Airship project.

| URL | Description |
|-----|-------------|
| `https://wallet-api.urbanairship.com/v1` | The North American base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an `Api-Revision` header, with a more specific version number, e.g., `1.2`. |
| `https://wallet-api.asnapieu.com/v1` | The European base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an `Api-Revision` header, with a more specific version number, e.g., `1.2`. |
| `https://oauth2.asnapius.com` | The North American base URL for OAuth token requests and public key verification. Use this when requesting an access token or verifying a key for the North American cloud site. |
| `https://oauth2.asnapieu.com` | The European base URL for OAuth token requests and public key verification. Use this when requesting an access token or verifying a key for the European cloud site. |
| `https://reach-api.urbanairship.com/v1` | The deprecated base URL for Wallet (formerly known as Reach) endpoints. Use `https://wallet-api.urbanairship.com/v1` instead. |

## Authentication {#security}

### Basic Auth (OAuth) {#security-basicOauth}

Type: `http` (basic)

Authorization header containing the word `Basic` followed by a space and a Base64-encoded string generated from your OAuth Client ID and Client Secret in `client_id:client_secret` format. For example, `Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0`. Used only for requesting OAuth tokens. See [OAuth](/docs/developer/rest-api/wallet/operations/oauth/).

### Basic Auth {#security-httpBasic}

Type: `http` (basic)

All Wallet operations support [basic authorization](https://en.wikipedia.org/wiki/Basic_access_authentication). The authorization header contains the word `Basic` followed by a space and a Base64-encoded string generated from your Project Key and Project Secret in `projectKey:projectSecret` format. For example, `Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0`.
        
  You can copy your Project Key and Secret from your Wallet project. Go to **Settings**, then **API**. For TLS and cipher requirements, see [TLS and supported ciphers](#tls-and-supported-ciphers) below.


### OAuth 2.0 {#security-oauth2Token}

Type: `oauth2`

Authorization header containing the word `Bearer` followed by a space and an OAuth 2.0 JWT bearer token provided by our authorization server. See [OAuth](/docs/developer/rest-api/wallet/operations/oauth/). Make sure your requests are using the appropriate [domain in the base URL](/docs/developer/rest-api/wallet/introduction/#servers).

| Scope | Description |
|-------|-------------|
| `wadl` | Adaptive Links |
| `wevt` | Events |
| `wfli` | Flights |
| `wnot` | Notifications |
| `wpas` | Passes |
| `wprj` | Projects |
| `wrpt` | Statistics |
| `wsch` | Schedules |
| `wseg` | Segments |
| `wtmp` | Templates |