Skip to main content
RestWard
Create a free account
API Reference

API keys & tenant API auth

Create API keys and authenticate requests to your generated tenant APIs, with examples in curl, Python, JavaScript and C#.

RestWard provides multiple ways for your consumers to authenticate API requests. The most common method is API Key authentication, where you issue keys tied to specific APIs and permission levels.

Authentication methods

RestWard supports three authentication methods:

  • API Key - Simple key-based auth; key sent in the X-API-Key header
  • JWT - JSON Web Token auth; token sent in the Authorization: Bearer header
  • mTLS - Mutual TLS certificate-based auth for high-security environments

Each method can be enabled or disabled per organization. Go to Auth & Keys to toggle methods on/off.

Issuing API keys

API keys grant consumers access to specific APIs. Each key has:

  • A friendly Key Name (e.g., "Production Mobile App")
  • An assigned API (which API the key can access)
  • A Role with permission level
  • An optional IP allowlist (see Restricting a key to IP addresses)
  • A unique key string (shown once after creation, never again)

To issue an API key:

  1. Go to Auth & Keys
  2. Click New API Key
  3. Enter the Key Name
  4. Select the API from the dropdown
  5. Choose the Role:
    • Read Only - Can read data (GET requests only)
    • Read & Write - Can read and create/update data (GET, POST, PUT)
    • Admin - Full access (all HTTP methods, all operations)
  6. Optionally, enter Allowed IP addresses (one per line) to restrict where the key can be used from
  7. Click Create Key
  8. Copy the key immediately - it displays only once in plaintext
  9. Click Done

The key now appears in your API Keys table as Active. Share it with your consumer in a secure channel (email, secure messaging, etc.).

API keys end-to-end walkthrough

This step-by-step guide takes you from creating a key through its full lifecycle: create, scope to an API, set a per-key rate limit, test a call, rotate, revoke, and permanently delete.

Prerequisites

  • You have at least one API created in your organization. See Building & publishing APIs if you need to create one.
  • You have the Contributor role or above in your organization (required to create and manage keys).

1. Create an API key

Dashboard:

  1. Go to Auth & Keys
  2. Click New API Key
  3. Enter a Key Name (e.g., "Production Mobile App")
  4. Select your API from the dropdown
  5. Choose a Role (e.g., Read & Write)
  6. Optionally, enter Allowed IP addresses (one per line) to restrict where the key can be used from
  7. Click Create Key
  8. Copy the key immediately — it displays only once in plaintext
  9. Click Done

CLI:

Shell
restward keys create --name "Production Mobile App" --api my-api
# The CLI returns the plaintext key once; store it securely

Verification: The key appears in your API Keys table with status Active.

2. Scope the key to a specific API

API keys are always scoped to a single API at creation time. The API dropdown in the dashboard (or the --api flag in the CLI) ensures each key can only access its assigned API. You cannot change a key's API after creation; to access a different API, create a new key for that API.

Dashboard: The key's API column shows which API it's scoped to.

CLI: The --api flag in restward keys create assigns the key to that API.

Verification: Attempting to use the key with a different API returns 401 Unauthorized.

3. Set a per-key rate limit

Each key has its own per-minute request quota. The default is 60 requests per minute, and the value is clamped at your plan's per-key ceiling. The rate limit cannot be customized in the dashboard or CLI at creation time; it always uses the default 60 (or your plan's ceiling if lower).

Dashboard: The Rate/MIN column in the API Keys table shows the effective rate limit for each key. The create form has no rate limit field; it uses the default.

CLI: The CLI uses the default 60 requests per minute when creating keys:

Shell
restward keys create --name "High Volume App" --api my-api
# Uses default 60 requests/minute, clamped at your plan's ceiling

Verification: The key's rate limit appears in the Rate/MIN column of the API Keys table. For details on how rate limiting works and client-side backoff patterns, see Rate limiting.

4. Test the key with a call

Use the key to make a request to your API.

Dashboard: Use the plaintext key you copied during creation (step 1). The Key column shows only a masked version for reference; the masked key cannot authenticate and will return 401 Unauthorized.

CLI: Use the plaintext key you saved during creation.

Example request:

Shell
curl -H "X-API-Key: rw_abcd1234..." \
  https://YOUR-API-HOSTNAME/api/public/users

Verification: A successful call returns the requested data. The Requests counter in the API Keys table increments, and Last Used updates to show when the key was last used. If you lost the plaintext key, you must rotate it (step 5) to generate a new one.

5. Rotate the key

Rotation generates a new key string while keeping the same name, API, and settings. The old key becomes invalid immediately.

Dashboard:

  1. In the API Keys table, find the key
  2. Click Rotate key (refresh icon, only visible on active keys)
  3. The new key is shown once in a success banner at the top of the API Keys section
  4. Copy it and update your consumer's configuration, then dismiss the banner

CLI:

Shell
restward keys rotate <key>
# Prints the new key once; store it securely

Verification: The old key immediately stops working. The new key works with the same permissions and IP allowlist as the old key.

6. Revoke the key

Revoking disables a key without deleting it. Requests using the revoked key are rejected within 30 seconds.

Dashboard:

  1. In the API Keys table, find the active key
  2. Click Revoke key (trash icon)
  3. Confirm the action
  4. The key status changes to Revoked

CLI:

Shell
restward keys revoke <key> [--yes]
# Asks for confirmation unless --yes; non-interactive mode requires --yes

Verification: Consumer requests using the revoked key receive 401 Unauthorized. The key's status in the table shows Revoked.

7. Permanently delete the key

Deletion permanently removes a revoked key from your system. This is only possible for already-revoked keys and requires Administrator role.

Dashboard:

  1. In the API Keys table, find the revoked key
  2. Click Delete key (red trash icon)
  3. Confirm the action
  4. The key is permanently deleted

CLI: Permanent deletion is done in the dashboard.

Verification: The key no longer appears in the API Keys table. If you need to re-enable access, issue a new key.

Managing API keys

Who can manage keys

Managing keys — creating, rotating, revoking, changing the IP allowlist, or permanently deleting — requires the Contributor role or above in the organization. Auditor and Reader are read-only: they can list and view keys but every change is refused with 403 Forbidden. The role is read from your current membership, so a role change applies at once.

Two ceilings apply on top of that:

  • A Contributor cannot create or manage a key with the Admin key role — only Administrators can. (Revoking an Admin-role key is also Administrator-only.)
  • Permanently deleting a key (after revoking it) is for Administrators only.

Finding and viewing keys

All keys appear in the API Keys table with columns:

  • Name - key identifier
  • API - which API the key accesses
  • Status - Active or Revoked
  • Key - masked key (e.g., rest_****...****) with a copy button
  • Role - Read Only, Read & Write, or Admin
  • Requests - total API calls made with this key
  • Last Used - relative time (e.g., "5 min ago", "never")

Rotating a key

Rotating generates a new key string while keeping the same name and API. The old key becomes invalid immediately.

  1. In the API Keys table, find the key
  2. Click Rotate key (refresh icon, only visible on active keys)
  3. The new key is shown once in a success banner at the top of the API Keys section
  4. Copy it and update your consumer's configuration, then dismiss the banner

Old key: immediately invalid. New key: immediately active. The new key keeps the old key's IP allowlist.

Restricting a key to IP addresses

A key can be limited to the addresses its consumer calls from. A request that carries the key from any other address is refused with 403 Forbidden (IP address not allowed.), on the API and on private documentation alike. A key with no entries can be used from anywhere.

In Auth & Keys, enter the Allowed IP addresses when you create the key, or use Edit IP allowlist on an active key to change it later. Enter one entry per line (commas also work):

  • an IPv4 or IPv6 address: 203.0.113.7, 2001:db8::1
  • a CIDR range: 203.0.113.0/24, 2001:db8::/32. The address must be the network address of the range: 10.1.2.3/8 is refused (use 10.0.0.0/8)

Entries are stored in a normalised form (IPv6 in lower case and compressed, /32 on an IPv4 address dropped, duplicates removed), at most 50 per key. An entry that is not valid is refused and named in the message. Clear the field to remove the restriction.

From the CLI:

Shell
restward keys create --name ci --allowed-ips "203.0.113.0/24, 2001:db8::/32"
restward keys allowed-ips ci --set 203.0.113.0/24
restward keys allowed-ips ci --clear

Over the platform API, PUT /api/v1/organizations/{orgId}/api-keys/{keyId}/allowed-ips with { "allowedIpRanges": ["203.0.113.0/24"] } replaces the list (an empty list removes the restriction), and allowedIpRanges can be sent when creating a key. Each change is recorded in the audit log (api-key.allowed-ips-changed).

Timing. Your API reads its keys again every 30 seconds (the EndpointConfig:RefreshSeconds setting of the API runtime), so a change, including one that tightens the list, applies to the running API within 30 seconds. Nothing is cached longer than that. If your API cannot reload its keys at all for several minutes (ten refresh intervals, 5 minutes by default), it stops accepting credentials and answers 503 until a reload succeeds, rather than keep trusting an old list.

Which address is compared. The client address as the API sees it: behind the platform's reverse proxy, the address the proxy appends to X-Forwarded-For (headers from any other source are ignored, so a caller cannot choose its own address); otherwise the address of the connection. Consumers behind a NAT or a corporate proxy are identified by that gateway's address.

Restricting JWT and mTLS callers to IP addresses

JWT tokens and client certificates are not tied to one key, so their allowlist belongs to the method: Allowed IP addresses in the Configure dialog of JWT Bearer or Mutual TLS in Auth & Keys. It applies to every token or certificate accepted by that method, after the token or certificate has been checked. A request from another address is refused with 403 Forbidden (IP address not allowed.). The field takes the same entries as a key's list (addresses and CIDR ranges, IPv4 and IPv6, at most 50, one per line), is checked as you type, and an empty field means no restriction. Over the platform API, send allowedIpRanges in the method's configuration JSON; a malformed entry refuses the whole save.

  • The two methods have separate lists; a key keeps using its own list, and a key without a list is not restricted by the JWT or mTLS lists.
  • Do not lock yourself out. The dialog shows the address you are browsing from and warns when it is not in the list. Your servers' addresses are usually different from your browser's, so check the callers' public addresses (a NAT or egress gateway, not a private address) before saving. To undo a mistake, clear the field and save.
  • The change applies within 30 seconds, like the other method settings.
  • The address compared is the same as for keys (see above): the address the platform's reverse proxy appends to X-Forwarded-For, and the connection's address when the request does not come through a trusted proxy.

Revoking a key

Revoking disables a key without deleting it. Requests using the revoked key are rejected as soon as your API has read its keys again: within 30 seconds (see Timing above).

  1. In the API Keys table, find the active key
  2. Click Revoke key (trash icon)
  3. Confirm the action
  4. The key status changes to Revoked

Revoking cannot be undone. A revoked key can only be permanently deleted (see below); to restore access, issue a new key.

After revocation, consumer requests using that key receive a 401 Unauthorized error.

Deleting a key

Deletion permanently removes a key from your system. This is only possible for already-revoked keys.

  1. In the API Keys table, find the revoked key
  2. Click Delete key (trash icon in red)
  3. Confirm the action
  4. The key is permanently deleted

A deleted revoked key cannot be recovered. If you need to re-enable access, issue a new key.

Calling your API with a key

Once you have an API key, consumers call your API by including the key in the request header.

Replace rw_abcd1234... with your key and https://YOUR-API-HOSTNAME with your API's endpoint (shown on the API's detail page in the dashboard, for example https://chinook-test-org-vzubqp.run.restward.tech). Each table is served at /api/<schema>/<table>, here the users table in the public schema. More examples, including JWT and client-certificate authentication, are in Authentication.

curl -H "X-API-Key: rw_abcd1234..." \
  https://YOUR-API-HOSTNAME/api/public/users
const headers = {"X-API-Key": "rw_abcd1234..."};
const response = await fetch(
  "https://YOUR-API-HOSTNAME/api/public/users",
  {headers}
);
import requests

headers = {"X-API-Key": "rw_abcd1234..."}
response = requests.get(
  "https://YOUR-API-HOSTNAME/api/public/users",
  headers=headers
)
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "rw_abcd1234...");
var response = await client.GetAsync(
  "https://YOUR-API-HOSTNAME/api/public/users"
);

Rate limiting and key usage

Each API key has its own per-minute request quota, set on the key. JWT callers have one per token subject and client certificates one per certificate, set in the JWT and mTLS settings (default 60); all are capped at your plan's per-key limit. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When a caller uses up its quota, its requests get 429 Too Many Requests with Retry-After set to the seconds left in the one-minute window. Other callers are not affected. See Rate limiting for details on how limits work, choosing values, and client-side backoff patterns, or Errors & rate limits for practical code examples.

Monitor Requests and Last Used in the API Keys table to track key usage.

Troubleshooting

"New API Key" button is disabled

You must have at least one API created. See Building & publishing APIs to create one first.

I lost my API key after creating it

API keys display only once after creation. If you didn't copy it, the plaintext key is gone. Rotate the key to generate a new one, or delete and issue a new key.

Consumer gets 401 Unauthorized

  • Verify the key is Active (not Revoked) in the API Keys table
  • Confirm the key is included in the request header as X-API-Key: {key}
  • Check the key hasn't exceeded the endpoint's rate limit (consumer may need to wait before retrying)

Consumer gets 403 Forbidden

The key's Role may be too restrictive. For example:

  • Read Only keys cannot make POST, PUT, or DELETE requests
  • Upgrade the key's role by revoking it and issuing a new one with a higher permission level

A 403 with IP address not allowed. means the key has an IP allowlist and the request came from another address: add the consumer's address to the key's allowlist (a change applies within 30 seconds). For JWT and mTLS callers the list is on the method: add the address under Configure > Allowed IP addresses.

How do I rotate a key without downtime?

  1. Create a new key with the same name (different API key string)
  2. Share the new key with your consumer
  3. Once they've switched their configuration, revoke the old key
  4. This ensures continuous service

Can I have multiple keys for one API?

Yes. Each consumer can have its own key, and you can revoke individual keys without affecting others on the same API.

Reconnecting to server...

Please wait while we restore your connection

Connection lost

Retrying in seconds...

Unable to reconnect

The server connection has been lost.
You may need to log in again.

Session Paused

The server has temporarily paused your session.

Session Expired

Your session could not be resumed.
Please reload the page to continue.