Skip to main content

Permissions via API Keys

API keys in RelayX control what a client is allowed to do after it connects.

Permissions do not change how RelayX behaves internally.
They only decide which actions are allowed for a given key.

This page explains:

  • What permissions exist
  • How they work
  • How to configure them correctly
  • What happens when a permission is missing or a key is disabled

What an API Key Represents​

An API key represents:

  • An identity
  • A set of allowed actions
  • An optional expiry
  • An environment scope (Test or Production)

When a client connects using an API key, RelayX checks:

  1. Is the key enabled?
  2. Is the key expired?

If any of these checks fail, the request is rejected with an Authorization Violation error.

Where Permissions Are Configured​

Permissions are managed from the Developer Console.

To edit permissions:

  1. Open the Developer Console
  2. Select API Keys from the left-hand menu
  3. Select the API key you want to modify
  4. Disable the key using the enable/disable switch

When the key is disabled:

  • Existing connected clients are disconnected
  • New clients cannot authenticate
  • The permissions form becomes editable

When the key is enabled:

  • Clients can authenticate and connect
  • Permissions are locked and cannot be edited

This prevents permission changes while a key is actively in use.

Permission Model Overview​

RelayX permissions are defined per primitive:

  • Messaging (Pub/Sub)
  • Queues
  • Key-Value Store

Each primitive has its own permission rules.

Messaging (Pub/Sub) Permissions​

Messaging permissions control publishing and subscribing separately.

Each API key has:

  • A Publish permission for topics
  • A Subscribe permission for topics

These permissions are configured independently.

Messaging – Publish Permissions​

info

To check what topics an API Key has enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it can publish to the topics you want.

Publish permissions control which topics a key can publish messages to.

Publish Permission Options​

For Publish, you can configure:

  • Scope
    • All
    • Only
  • Switch
    • Allowed (On)
    • Disallowed (Off)
  • Optional topic list (when using Only)

Publish Permission Behavior​

When Scope: All is selected:

  • Switch: Allowed (On)
    • The key can publish to all topics
  • Switch: Disallowed (Off)
    • The key cannot publish to any topic

When Scope: Only is selected:

  • Switch: Allowed (On)
    • The key can publish only to the listed topics
  • Switch: Disallowed (Off)
    • The key can publish to all topics except the listed ones

Messaging – Subscribe Permissions​

info

To check what topics an API Key has enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it can subscribe to the topics you want.

Subscribe permissions control which topics a key can subscribe to.

Subscribe permissions are evaluated independently from publish permissions.

Subscribe Permission Options​

For Subscribe, you can configure:

  • Scope
    • All
    • Only
  • Switch
    • Allowed (On)
    • Disallowed (Off)
  • Optional topic list (when using Only)

Subscribe Permission Behavior​

When Scope: All is selected:

  • Switch: Allowed (On)
    • The key can subscribe to all topics
  • Switch: Disallowed (Off)
    • The key cannot subscribe to any topic

When Scope: Only is selected:

  • Switch: Allowed (On)
    • The key can subscribe only to the listed topics
  • Switch: Disallowed (Off)
    • The key can subscribe to all topics except the listed ones

Important Notes for Messaging Permissions​

  • Publish and Subscribe permissions are enforced independently
  • Topic matching is exact
  • Permissions are enforced at runtime
  • Changing permissions requires disabling the API key first
  • Messaging permissions do not affect ordering, deduplication, or delivery semantics

Queue Permissions​

Queue permissions are applied per queue, not globally.

Each queue has its own permission configuration.

An API key may be allowed to publish jobs to some queues and subscribe workers to others.

Publish and Subscribe permissions are configured independently for each queue.

Queue – Publish Permissions​

info

To check what topics an API Key has enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it can publish to the topics you want.

Publish permissions control which topics within a queue a key can publish jobs to.

Publish Permission Model (Per Queue)​

For each queue, the API key has a Publish permission.

Permissions are evaluated:

  • Per queue
  • Per action (Publish)
  • Per topic within that queue

Publish Permission Options​

For a given queue and for the Publish action, you can configure:

  • Scope
    • All
    • Only
  • Switch
    • Allowed (On)
    • Disallowed (Off)
  • Optional topic list (when using Only)

Publish Permission Behavior​

For a given queue:

  • Scope: All + Switch: Allowed (On)

    • The key can publish jobs to all topics in this queue

  • Scope: All + Switch: Disallowed (Off)

    • The key cannot publish jobs to any topic in this queue

When Scope: Only is selected:

  • Scope: Only + Switch: Allowed (On)

    • The key can publish jobs only to the listed topics in this queue

  • Scope: Only + Switch: Disallowed (Off)

    • The key can publish jobs to all topics except the listed ones in this queue

Queue – Subscribe Permissions​

info

To check what topics an API Key has enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it can subscribe to the topics you want.

Subscribe permissions control which topics within a queue a key can subscribe workers to.

Subscribe permissions are evaluated independently from publish permissions.

Subscribe Permission Model (Per Queue)​

For each queue, the API key has a Subscribe permission.

Permissions are evaluated:

  • Per queue
  • Per action (Subscribe)
  • Per topic within that queue

Subscribe Permission Options​

For a given queue and for the Subscribe action, you can configure:

  • Scope
    • All
    • Only
  • Switch
    • Allowed (On)
    • Disallowed (Off)
  • Optional topic list (when using Only)

Subscribe Permission Behavior​

For a given queue:

  • Scope: All + Switch: Allowed (On)

    • The key can subscribe workers to all topics in this queue

  • Scope: All + Switch: Disallowed (Off)

    • The key cannot subscribe workers to any topic in this queue

When Scope: Only is selected:

  • Scope: Only + Switch: Allowed (On)

    • The key can subscribe workers only to the listed topics in this queue

  • Scope: Only + Switch: Disallowed (Off)

    • The key can subscribe workers to all topics except the listed ones in this queue

Important Notes for Queue Permissions​

  • Queue permissions are enforced per queue, per action, and per topic
  • Publish and Subscribe permissions are evaluated independently
  • Changing permissions requires disabling the API key
  • Queue permissions do not affect delivery guarantees or retry behavior

Permissions only control access to topics within a queue, not how jobs are processed.

Key-Value Store Permissions​

KV Store permissions are simpler and use checkboxes.

There are two permissions:

  • Read
  • Write

Read Permission​

info

To check if an API Key has KV Store read enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it has read permissions for the KV Store.

When Read is enabled:

  • The client can read values by key
  • The client can list all keys in the KV Store

When Read is disabled:

  • Reads are blocked
  • Listing keys is blocked

Write Permission​

info

To check if an API Key has KV Store write enabled / disabled, go to the API Key section of the Developer Console. Click on the key your client is using and make sure it has write permissions for the KV Store.

When Write is enabled:

  • The client can create or update key-value pairs
  • The client can delete keys

When Write is disabled:

  • Writes are blocked
  • Deletes are blocked

Write permission always includes delete.

KV Store Notes​

  • KV permissions do not affect consistency behavior
  • Last-write-wins semantics remain unchanged

Key Expiry​

Each API key can have an optional expiry date and time (UTC).

  • If no expiry is set:
    • The key is valid indefinitely
  • If an expiry is set:
    • The key is valid until that exact time

When a key expires:

  • All connected clients are immediately disconnected
  • New connections are rejected
  • Clients receive an Authorization Violation error

Expiry is enforced automatically by RelayX.

Environment Scope​

Each API key is scoped to an environment:

  • Test
  • Production

Environment scope ensures:

  • Test messages do not mix with production messages
  • Topics, queues, and messages remain isolated

Environment selection applies to:

  • Messaging (Pub/Sub)
  • Queues
  • KV Store

A key scoped to Test cannot access Production resources, and vice versa.

Enabling and Disabling Keys​

info

To check if an API Key is enabled / disabled, go to the API Key section of the Developer Console. Make sure the keys your client is using is active.

API keys can be enabled or disabled at any time.

Enabled Key​

When a key is enabled:

  • Clients can authenticate and connect
  • Permissions are enforced
  • Permissions cannot be edited

Disabled Key​

When a key is disabled:

  • Existing connected clients are disconnected
  • New clients cannot authenticate
  • Clients receive an Authorization Violation error
  • Permissions become editable in the console

Disabling a key is the only way to modify its permissions.

Common Mistakes​

  • Assuming permissions can be edited while a key is enabled
  • Forgetting that Only + Switch OFF acts as a block-list
  • Assuming KV write permission allows reads
  • Assuming expiry is advisory rather than enforced

Summary​

API key permissions in RelayX:

  • Control access, not behavior
  • Are enforced at runtime
  • Apply per primitive
  • Support allow-lists and block-lists
  • Can be updated safely by disabling the key
  • Support expiry and environment isolation

Permissions are designed to be explicit and predictable.

If an action is not allowed, it fails immediately.



Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️