# App Keys & Secrets: Security

In order for your app to communicate with the Airship API it must use a key and secret combination that authenticates it to your Airship app setup.

These keys are generated automatically when you
create an app in our dashboard, and you manually copy them into your iOS, Android/Fire OS, or Windows
app configuration. Since app bundles are fundamentally considered insecure (they can be decompiled),
this key and secret combination limits the APIs that your device can communicate with. This allows the
device to modify tags and named user for a specific channel, device token, or APID, and nothing more.

Push addresses/tokens are sufficiently random that they can be considered obscure, and the associated data is low risk.
We employ additional security on our servers to monitor for abuse. Tags and named user should be considered
obscure, however they are trusted APIs for devices to access so you should not place sensitive information
in a tag or named user.

We generate one additional piece of data called the Master Secret, which is used to do all
communication with our wider APIs. The Master Secret should never be placed in an app bundle, nor released
to the public. This is the secret you use to authenticate requests to our server for generating pushes, rich
app pages, and more.

## Definitions

App Key
: Airship-generated string identifying the app setup. Used in the application bundle. Only available in the Airship dashboard.

App Secret
: Airship-generated string identifying the app setup secret. Used in the application bundle. Only available in the Airship dashboard.
This can be reset by Airship's Support team, but only for emergency security issues. If you want to change this periodically,
we suggest you use the bearer token instead.

Master Secret
: Airship-generated string used for server-to-server API access. This secret must never be shared or
placed in an application bundle. Only available in the Airship dashboard. This can be reset by Airship's Support team, but only for
emergency security issues. If you want to change this periodically, we suggest you use the bearer token instead.

Partner Secret
: Airship-generated string used for server-to-server API access to create and manage applications for
partner integrations. This should never be shared or placed in an application bundle. Only available
through manual channels.

Bearer Token
: A token you can create and revoke from within Airship to be used for custom event servers, SMS webhook servers, and API consumers.
Because you can create and revoke tokens for your team at will, bearer authentication maximizes your control over who can access Airship.
This should never be shared or placed in an application bundle. Only available in the Airship dashboard.

User ID
: Airship-generated string passed back to devices and stored in the device keychain for authenticating
user-related device API actions when paired with the Password. This is not the same as your Airship
dashboard user ID.

Password
: Airship generated string passed back to devices and stored in the device keychain for authenticating
User related device API actions when paired with the User ID. This is not the same as your Airship dashboard password.

Push Address *or* Token
: A unique proprietary string generated by device vendors (Apple, Google, Windows, Fire OS) for
identifying an addressable push device. This is passed back to the device via vendor specific APIs and
then stored by Airship for addressing push messages and authenticating push related APIs.

<!-- Purchase Receipt (commented this out 4/24/14 because kiling iap docs- pfd) -->
<!-- A proprietary digital signed receipt for an in-app purchase that is vendor specific (Apple, Google). -->
<!-- Used to verify purchase authenticity in an out-of-band server-to-server verification from Airship -->
<!-- to the vendor-specific verification API. -->

Dashboard User ID and Password
: The credentials used to log in to the Airship [Dashboard](https://www.airship.com/docs/reference/glossary/#dashboard).

## API Authentication Map

| API feature | Create | Read | Update | Delete |
|  --- |  --- |  --- |  --- |  --- |
| Tags | App Key/Secret & Token | Single: App Key/Secret & Token Enumerate: App Key/Secret | App Key/Secret & Token | Single from Device: App Key/Secret & Token All tags, all devices: Master Secret |
| Device Token/APID/PIN Registration | App Key/Secret & Token | Single: App Key/Secret & Token Enumerate: Master Secret | App Key/Secret & Token | App Key/Secret & Token<sup>1</sup> |
| Push Message | Master Secret<sup>2</sup> | Scheduled Push: Master Secret | Scheduled Push: Master Secret | Scheduled Push: Master Secret |
| Rich Push Message | App Key/Master Secret | User ID/Password | N/A | User ID/Password |
| User | App Key/Master Secret | Single: User ID/Password or Master Secret Enumerate: Master Secret | User ID/Password or Master Secret | User ID/Master Secret<sup>1</sup> |
| Partner API | Partner Key/Secret<sup>3</sup> | Partner Key/Secret | Partner Key/Secret | Partner Key/Secret |

<sup>1. Marks as inactive.</sup><br>
<sup>2. Unless push from device feature.</sup><br>
<sup>3. Only available to Airship partners.</sup>

## Tag & Named User Security

Tags and named users are considered obscure, but not secure in our system. We recommend that you not use
them to store sensitive information. The obscurity varies by platform, as push addresses/tokens are a different
format for each vendor (Apple, Google, Microsoft, Fire OS). Typically these are UUIDs or similar,
but this is not guaranteed and should be considered proprietary in nature. To gain access to
a specific device's tags or the named user it belongs to from an unauthorized source you would need to guess the push
identifier, which is mathematically improbable, or obtain it by other means.

Given that certain tag operations can be completed without the master secret it is possible for a user,
with the app key, secret, and push address, to list tags for an app and subscribe or unsubscribe themselves
to those tags. Please be aware of this as you plan your own usage of the tag API.