Airship 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

HTTP authentication supports Basic Auth and Bearer Token. OAuth authentication supports OAuth 2.0.

The basic differences between authentication methods:

For a list of endpoints allowed per authentication method, see the Airship 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 Airship API reference and Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. 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 and authorization. You provide your project’s App KeyThe unique identifier for your Airship project. It is used to authenticate the application for API calls. and App SecretA secret used to authorize requests for low-security API calls. It is intended to be embedded in your distributed application, and as such is limited in what it can do. or Master SecretA secret that can be used as the Basic authorization password for any API call. Guard the Master Secret carefully, and never embed it in an application you distribute to users. to generate a Base-64 authorization string. The App Secret grants access to most product features, while the Master Secret grants access to the majority of the Airship API.

While Basic Master grants access to the complete Airship API, you should use this method for server-to-server communications only. You should not give out your Master Secret or use Basic Master authentication with your app. See the Basic Authentication Map for more information about the features you can access with Basic Auth.

To access your App Key, App Secret, and Master Secret for an Airship project, go to Settings in the dashboard. Access level Owner, Administrator, or Full Access is required to view the Master Secret.

In the API reference, see:

• Base URLs for HTTP authentication in the Base URLs section
• HTTP Authentication: Basic Auth (App) and Basic Auth (Master) in the Authentication section

Bearer Token

Bearer Token is a form of HTTP authentication and authorization. You provide a token string generated from your Airship project settings. You can set bearer tokens to allow complete access to all endpoints and features that support Bearer Token authentication or only allow registering and modifying audiences. Bearer tokens do not expire. To revoke access, you must delete the token.

You create and delete bearer tokens in your project settings. See next page section.

In the API reference, see:

• Base URLs for HTTP authentication in the Base URLs section
• HTTP Authentication: Bearer Token in the Authentication section

Creating bearer tokens

First determine which access role you need for your token. See the columns Bearer — All Access and Bearer — Audience Modification in the Airship API authorization reference.

Then create the token in your Airship project:

1. Go to Settings.
2. Under Project Configuration, select Manage for Tokens.
3. Select Create token.
4. Enter a token name. This is used to recognize your tokens in Airship.
5. Select an access role for the token:

   Role	Description	Typical use
   Audience Modification	Grants read and write permission to audience-related APIs	Sending custom events into Airship
   All Access	Grants full access to your Airship project	Inbound message handling webhooks

6. Select Create token.
7. Copy the App Key and token strings, then select Got it to close the window. You cannot view the token again after closing.

Managing bearer tokens

To view a list of your tokens, first go to Settings. Then, under Project Configuration, select Manage for Tokens. The default sort order is by last created, and each row displays the token name, assigned role, and creation date and time.

To immediately revoke a token’s access to the Airship API, select Delete.

OAuth 2.0

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

This method provides better security than Basic Auth and Bearer Token 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:

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 HTTP Basic Auth with 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 API reference, see:

• Base URLs for OAuth authentication in the Base URLs section
• HTTP Authentication: Basic Auth (OAuth) in the Authentication section
• OAuth Authentication: OAuth 2.0 in the Authentication section
• OAuth API
• Assertion JWT in the Data Formats section

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

1. Go to Settings.
2. Under Project Configuration, select Manage for OAuth.
3. Select Add credentials.
4. Enter a name and description to help you identify them in your list of all client credentials.
5. Configure options:

   Option	Description	Configuration
   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.

6. Select Next.
7. 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 Airship API authorization reference.
8. Select Save.
9. Select the copy icon for each credential string or select Download all to save them in a zip file.
10. Select Close. After closing, only the Client ID and Public Key are accessible in the Airship dashboard.

Requesting tokens

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

Managing client credentials

To view a list of your client credentials, first go to Settings. Then, under Project Configuration, select Manage for OAuth. 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 filter by status: Active, Revoked, or Expired.

Client credentials management options: