# Airship API Security The Airship messaging API supports HTTP and OAuth authentication. Different security and authorization levels are available for both. 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:
Authentication method Credentials Lifetime API permissions
Basic Auth [App Key](https://www.airship.com/docs/reference/glossary/#app_key) and [App Secret](https://www.airship.com/docs/reference/glossary/#app_secret) or [Master Secret](https://www.airship.com/docs/reference/glossary/#master_secret) 🚨 Permanent 🚨 Master Secret allows access to most APIs, App Secret allows access to only the APIs necessary for providing Airship access to your audience's apps and browsers.
Bearer Token A token created in the dashboard Until revoked Role-based. Audience Modification grants access to register and modify audiences. All Access grants complete access to all endpoints and features that support Bearer Token authentication.
OAuth 2.0 A token generated by a POST using credentials created in the dashboard Token=1 hour
Credentials=Until expiration, if set		 Scope-based. Specify one or more scopes that define allowed endpoints and operations.
![Supported authentication methods listed for POST /api/push](https://www.airship.com/docs/images/send-push_hu_a7bba359be8cd4c.webp) *Supported authentication methods listed for POST /api/push* For a list of endpoints allowed per authentication method, see the [Airship API Authorization Reference](https://www.airship.com/docs/developer/rest-api/ua/api-auth-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](https://www.airship.com/docs/developer/rest-api/ua/) and [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) [API reference](https://www.airship.com/docs/developer/rest-api/connect/), 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 Key](https://www.airship.com/docs/reference/glossary/#app_key) and [App Secret](https://www.airship.com/docs/reference/glossary/#app_secret) or [Master Secret](https://www.airship.com/docs/reference/glossary/#master_secret) 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](https://www.airship.com/docs/guides/getting-started/developers/app-keys-secrets/#api-authentication-map) for more information about the features you can access with Basic Auth. You can access your App Key, Secret, and Master Secret in your project dashboard. Next to your project name, select the dropdown menu ( ), then **Project Details**. Access level [Owner, Administrator, or Full Access](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) is required to view the Secret. Owner and Administrator can view the Master Secret. In the API reference, see: * [Base URLs for HTTP authentication](https://www.airship.com/docs/developer/rest-api/ua/introduction/#servers) in the *Base URLs* section * [HTTP Authentication: Basic Auth (App) and Basic Auth (Master)](https://www.airship.com/docs/developer/rest-api/ua/introduction/#security) 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. In the API reference, see: * [Base URLs for HTTP authentication](https://www.airship.com/docs/developer/rest-api/ua/introduction/#servers) in the *Base URLs* section * [HTTP Authentication: Bearer Token](https://www.airship.com/docs/developer/rest-api/ua/introduction/#security) in the *Authentication* section ### Creating bearer tokens Project [Owners and Administrators](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) can create 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](https://www.airship.com/docs/developer/rest-api/ua/api-auth-reference/#authorization-per-authentication-method). Then create the token in your Airship project: 1. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Project settings**, select **Tokens**. 1. Select **Create token**. 1. Enter a token name. This is used to recognize your tokens in Airship. 1. 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 | 1. Select **Create token**. 1. 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 Project [Owners and Administrators](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) can manage bearer tokens. Next to your project name, select the dropdown menu ( ), then **Settings**. Then, under **Project settings**, select **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**. If your request returns an "Invalid bearer token" error, verify your token is active and includes the [access role necessary](https://www.airship.com/docs/developer/rest-api/ua/api-auth-reference/#authorization-per-authentication-method) for the given request. ## OAuth 2.0 [OAuth 2.0](https://oauth.net/2/) 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](https://www.airship.com/docs/developer/rest-api/ua/api-auth-reference/#oauth-token-scopes) 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. 1. 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. 1. Use the token for authentication in API calls. Make sure your requests are using the appropriate [domain](https://www.airship.com/docs/developer/rest-api/ua/introduction/#servers). 1. 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 Airship API reference, see: * [Base URLs for OAuth authentication](https://www.airship.com/docs/developer/rest-api/ua/introduction/#servers) in *Introduction* * [HTTP Authentication: Basic Auth (OAuth)](https://www.airship.com/docs/developer/rest-api/ua/introduction/#security) and [OAuth Authentication: OAuth 2.0](https://www.airship.com/docs/developer/rest-api/ua/introduction/#security) in *Introduction* * [OAuth API endpoints](https://www.airship.com/docs/developer/rest-api/ua/operations/oauth/) in *Operations* * [Assertion JWT](https://www.airship.com/docs/developer/rest-api/ua/schemas/oauth/#assertionjwt) 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](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) can create client credentials: 1. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Project settings**, select **OAuth**. 1. Select **Add credentials**. 1. Enter a name and description to help you identify them in your list of all client credentials. 1. 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. | 1. Select **Next**. 1. 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](https://www.airship.com/docs/developer/rest-api/ua/api-auth-reference/#oauth-token-scopes) in the *Airship API Authorization Reference*. 1. Select **Save**. 1. Select the copy icon for each credential string or select **Download all** to save them in a zip file. 1. Select **Close**. After closing, only the Client ID and Public Key are accessible in the Airship dashboard. ### Request tokens See [Request token](https://www.airship.com/docs/developer/rest-api/ua/operations/oauth/#requestoauthtoken) in the *OAuth* section of the API reference. ### Manage client credentials Project [Owners and Administrators](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) can manage client credentials. Next to your project name, select the dropdown menu ( ), then **Settings**. Then, under **Project settings**, select **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 can filter by status: Active, Revoked, or Expired. Client credentials management options: | Option | Description | Steps | | --- | --- | --- | | **Copy credentials** | You can view and copy the Client ID and Public Key. | Select the copy icon for each credential string, then select **Save**. | | **Edit credentials** | You can change the name, description, expiration, or permissions. | Select the edit icon ( ), edit, then select **Save**. | | **Revoke active or expired credentials** | Disables the credentials' ability to request new tokens from the authorization server. Tokens already issued will continue to be valid until their own expiration date and time. You cannot restore revoked credentials. | Select the revoke credentials icon. | | **Delete revoked credentials** | Removes the credentials from the list of all credentials | Select the delete icon ( ). |