Skip to content

REST API authentication

Protected endpoints at https://api.appelium.com use an API key in the X-Appelium-Token header. The key is created in the Dashboard and identifies both a workspace and the permissions available to the request.

Do not confuse a workspace API key with the application token used by the Appelium mobile SDK. SDK integrations send their application token with mobile telemetry; REST API calls use the X-Appelium-Token workspace key described on this page.

Create an API key

  1. Open API Access Settings in the Dashboard.
  2. Select New API Key.
  3. Choose the key type:
  4. Personal API key is tied to your user account and inherits your current role in the workspace.
  5. System API key belongs to the workspace, always has admin permissions, and can only be created and managed by a workspace admin.
  6. Give a system key a descriptive purpose such as GitHub Actions, release-automation or support-tools.
  7. Copy the token immediately and store it in your password manager or CI secret store.

The original token is shown only when it is created. Appelium stores a hash, so it cannot display or recover the original value later. If the token is lost, delete it and create a replacement.

Send the token

Supply the token on every request:

curl --request GET \
  --url https://api.appelium.com/v1/applications \
  --header 'X-Appelium-Token: YOUR_API_KEY'

The header is case-insensitive, but use the documented spelling. Do not put the key in the URL or query string: URLs can be retained in shell history, proxy logs and monitoring systems.

For curl, environment variables make local use and CI scripts safer:

curl --fail-with-body \
  --request GET \
  --url https://api.appelium.com/v1/applications \
  --header "X-Appelium-Token: $APPELIUM_API_KEY"

YOUR_API_KEY and $APPELIUM_API_KEY are placeholders. Never commit a real value to source control, an application bundle, a mobile resource, a Docker image or client-side JavaScript.

Permissions

Key type Identity Permission behaviour
Personal A Dashboard user The request inherits that user's current workspace role. Removing the user, deactivating the user or reducing the role also affects the key.
System The workspace The key has admin permission and remains usable independently of a single user's account. It is suitable for unattended automation.

Prefer a personal key for developer tooling and a narrowly scoped, separately named system key for automation. Do not share one key across unrelated services: separate keys make revocation and activity investigation possible without interrupting other integrations.

Authentication errors

Status Typical cause Next step
401 Unauthorized Header missing, key mistyped, key deleted or owning personal user is deactivated/deleted Check the header name and replace or recreate the key.
403 Forbidden The token is valid, but its resolved role cannot perform the operation Review the owning user's workspace role or use an appropriately permissioned key.
404 Not Found The resource does not exist in the key's workspace Verify that the resource ID belongs to the same workspace as the API key.

Rotate or revoke a key

When a key may be exposed:

  1. Create a replacement key without reusing the old token.
  2. Update the password manager, CI secret or deployment setting.
  3. Make a test call to List Applications.
  4. Delete the exposed key in Dashboard → Settings → API.

Deletion takes effect for subsequent API requests. If the key was included in a Git commit, pipeline log, support message or public build artifact, treat it as exposed even if the value was later removed from the visible source.

Next steps

Once authentication succeeds, use the Applications API to obtain the numeric application ID required by application-specific endpoints.