Xulo Docs

REST API

Authentication

Send the app's REST API key in a header. Keys are per app, shown once, can be locked to IP addresses, and can be revoked.

View as Markdown

Get a key

In the dashboard, open the app's Settings → Keys & IDs and create a REST key. Give it a name and, if you want, the IP addresses allowed to use it.

The key starts with xulo_. It is shown once, when you create it. Store it on your server, for example as XULO_REST_KEY. It must never ship inside an app.

Send the key

Any one of these headers works:

HTTP
Authorization: Key xulo_...
Authorization: Bearer xulo_...
X-Xulo-Key: xulo_...

A key in the query string is not accepted. The call returns 401.

One key, one app

A key belongs to one app.

  • The body's app_id must be that app's App ID. Another app's id returns 404.
  • If the body has a bundle_id, it must be that app's bundle id. Another bundle id returns 404.
  • GET /api/v1/notifications/{id} with another app's send returns 404.

An organization key that starts with perk_ is not a REST key and returns 401. So does the App ID.

IP lock

A key can be locked to IP addresses or ranges, such as 203.0.113.7 or 203.0.113.0/24. Set them when you create the key, or later under IP lock.

  • With no addresses set, every address is allowed.
  • With addresses set, a call from anywhere else returns 403, and the key's last use is not updated.

Revoke

Revoke a key in Settings → Keys & IDs. A revoked key returns 401.

Errors

Status Body When
401 {"message":"Missing REST API key."} No key in a header.
401 {"message":"Invalid REST API key."} The key is wrong or revoked.
403 {"message":"This REST key is locked to other IP addresses."} The IP lock refused the address.

See Errors for the rest.