API Key Authentication

Atlas Device Sync, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

Overview

The API Key authentication provider allows users to log in using generated keys.

App Services supports the following two types of API keys:

Server API keys: API keys associated with server users that is created from the App Services CLI, API or UI.
User API keys: API keys created from the Realm SDKs associated with application users.

API keys do not expire automatically.

Enable API Key Authentication

To work with API key users, you must first enable the API key authentication provider. The API Key authentication provider does not have any configuration options.

You can enable and configure the API Key authentication provider from the App Services UI by selecting API Keys from the Authentication page.

To enable and configure the API Key authentication provider with :ref:`App Services CLI <appservices-cli>`, define a configuration object for it in /auth/providers.json.

API Key provider configurations have the following form:

/auth/providers.json

{
  "api-key": {
    "name": "api-key",
    "type": "api-key",
    "disabled": false
  }
}

Tip

The name of an authentication provider is always the same as its type.

API Key User Objects

Every App Services user has a unique metadata object. The object is passed to Functions called by the user and rule expressions for requests made by the user. In API key user objects, the type field has the value "server". For example:

{
  id: "<Unique User ID>",
  type: "server",
  data: <user data object>,
  custom_data: <custom user data object>,
  identities: <array of user identities>,
}

You can use this field to evaluate if requests come from API keys.

For more information, refer to User Objects.

Server API Keys

Server API keys are generated in a server-side context using one of the App Services CLI, API or UI. When you create a server API key, you also create an associated server user.

You can provide a server key to external applications and services to allow them to authenticate directly with App Services.

You can associate up to 100 server API keys with an app.

Create a Server API Key

You must enable the API key provider before you can create an API key.

Important

You must copy the server key's value as soon as you create it. Once you create the API key, you can no longer retrieve it.

Select App Users from the left navigation menu.
Select the Authentication Providers button and then select the API Keys provider.
If the API Key provider is not currently enabled, you must enable it and then deploy your changes before you can create a key.
Click Create API Key.
Enter a unique name for the key and then click Save.

To create a new server API key, call appservices users create and specify --type=api-key. The CLI will prompt you for your App ID as well as a name for the new API key.

appservices users create --type=api-key

You can also specify the arguments when you call the program:

appservices users create --type=api-key \
  --app=<Your App ID> \
  --name=<API Key Name>

To create a server API key using the Admin API, make a request to the Create a new API key endpoint.

User API Keys

You can generate user API keys with the Realm SDKs. Each user API Key is associated with a single non-anonymous user. Each user can associate up to 20 user API keys with their account. Once the key is associated with a user account, the user can use the key to authenticate. The following diagram shows how to create, and then use, a User API Key:

To learn how to generate user API keys, refer to the Realm SDK documentation.

Realm SDK Examples

For code examples that demonstrate how to register and log in using API Key authentication, see the documentation for the Realm SDKs.

Log In With an API Key

The Realm SDK can log in with an existing server or user API key.

Create a User API Key

The Realm SDK can create a new user API key for an existing user account.

Back

Anonymous

Email/Password