Wallet API Security

Authentication verifies who is requesting access to the API. Authorization determines what the requester has access to. Use this page to determine what authentication you want to use and the levels of access you want to grant. It also contains setup procedures.

Supported authentication methods

The Wallet API supports HTTP Basic Authentication and OAuth 2.0.

The basic differences between authentication methods:

For a list of endpoints allowed per authentication method, see the Wallet API Authorization Reference.

In addition to the differences noted in the above table, the HTTP and OAuth methods use different base URLs. For detailed information, see each method’s section on this page.

In the Wallet API reference, each endpoint’s supported authentication methods, and scopes for OAuth 2.0, are listed under Security.

Basic Auth

Basic Auth is a form of HTTP authentication. You provide your project’s Project Key and Project Secret to generate a Base-64 authorization string. This method grants access to the entirety of the Wallet API for your project.

You can access your Project Key and Secret in your Wallet project dashboard. Go to Settings and select API.

OAuth 2.0

OAuth 2.0  is an authorization framework you can use to provide secure, limited access to the Wallet API. Instead of providing a single string like with Basic Auth, you regularly fetch short-lived bearer tokens to use in your API calls.

This method provides better security than Basic Auth since, in the event of the tokens becoming public, they can only be used for a short time before they expire. Another benefit is control of permissions. Instead of broad access to the API, you select one or more scopes that define which endpoints and operations are authorized for the tokens, and you can edit them at any time.

The general workflow for OAuth 2.0 and Airship Wallet:

1. Create client credentials in your Airship project settings and set the scope of permissions to authorize for issued tokens.

   You can also specify an expiration date and time for the credentials or revoke them later. After expiration or revocation, no tokens will be issued for requests using those credentials, but any tokens already issued will continue to be valid until their own expiration date and time.

2. Request a token in a POST using your client credentials or, for additional security, using an assertion.

   An assertion is a JSON Web Token (JWT) used for authentication. You may want to use an assertion since it does not require regularly transmitting long-lived secrets and provides some defense against replay attacks by requiring a nonce. However, it is less convenient, and OAuth clients are unlikely to support this flow.

   In your request, you can also restrict a token to specific scopes and/or IP addresses.

3. Use the token for authentication in API calls.

4. Refresh the token before it expires. The expires_in property in the response from the token request tells you the number of seconds from the time the token is generated until it expires.

   Keep refreshing until it is no longer needed, or revoke the credentials in the dashboard if you want to disallow further token requests.

In the Wallet API reference, see:

• Base URLs for OAuth authentication in Introduction
• HTTP Authentication: Basic Auth (OAuth) and OAuth Authentication: OAuth 2.0 in Introduction
• OAuth API endpoints in Operations
• Assertion JWT in Data Formats

Create client credentials

Client credentials are used for communicating with the authorization server that issues OAuth tokens. By default, the credentials are a Client ID, Public Key, and Private Key. You can also generate a Client Secret to use in HTTP Basic Auth token requests. You can edit the credentials’ name, expiration, and permissions after saving.

Project Owners and Administrators can create client credentials:

1. In your Wallet project, go to Settings and select OAuth.
2. Select Create credentials.
3. Enter a name and description to help you identify them in your list of all client credentials.
4. Configure options:

   Option	Description	Steps
   Allow Basic Auth	Generates a Client Secret for use in HTTP Basic Auth token requests. You cannot change this setting later.	Toggle to enable.
   Expiration	Sets the credentials to expire at a specific date and time. After expiration, no tokens will be issued for requests using the credentials, but any tokens already issued will continue to be valid until their own expiration date and time.	Toggle to enable, then enter a date and time in UTC.

5. Select Next.
6. Toggle to enable the scope of permissions for the issued tokens. For a list of endpoints and related operations allowed for each scope, see OAuth token scopes in the Wallet API Authorization Reference.
7. Select Save.
8. Select the copy icon for each credential string or select Download all to save them in a zip file.
9. Select Close. After closing, only the Client ID and Public Key are accessible in the Airship dashboard.

Request tokens

See Request token in the OAuth section of the API reference.

Manage client credentials

Project Owners and Administrators can manage client credentials.

Go to Settings and select OAuth to manage your client credentials. The default sort order is by last created, and each row displays the name, Client ID, status, description, creation date and time, and expiration date and time. You can search by name, Client ID, and description. You can filter by status: Active, Revoked, or Expired.

Client credentials management options: