Authentication

Relay customer API requests authenticate with an organization API key in the accesskey header.

http

accesskey: YOUR_ORGANIZATION_API_KEY

Server-side only#

An organization API key can create collection resources and read data belonging to its organization. Treat it like a password:

call Relay from your backend, never directly from a browser or mobile client;
store it in a secret manager or protected environment variable;
do not include it in source control, analytics, URLs, screenshots, or application logs; and
rotate it through your Relay onboarding contact if you believe it has been exposed.

javascript

const relay = async (path, init = {}) => {
  const response = await fetch(`https://bridge.relayfinance.io${path}`, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      accesskey: process.env.RELAY_ACCESS_KEY,
      ...init.headers,
    },
  });

  const body = await response.json();
  if (!response.ok) {
    const error = new Error(body.error?.message ?? "Relay request failed");
    error.code = body.error?.code;
    error.requestId = body.meta?.requestId;
    throw error;
  }
  return body.data;
};

Authentication failures#

Condition	HTTP status	Message
Header is missing	`401`	`Provide Access Key`
Key is invalid or the organization is inactive	`401`	`Invalid Access Key`
Authenticated organization does not own the resource	`404` or `400`	Resource-specific safe message

Authentication errors use the standard error envelope:

json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid Access Key"
  },
  "meta": {
    "requestId": "e4d95367-72b7-4638-ada4-1715ec98f37c"
  }
}

Tenant boundaries#

Every API-key request is scoped to the organization that owns the key. Relay does not use an organization ID supplied by the caller to select a tenant. A payment or wallet belonging to another organization is not returned.

Dashboard sessions are different#

The Relay dashboard uses bearer-token sessions and role permissions for human administration. Those endpoints manage settings such as settlement destinations, webhook endpoints, team access, and delivery replay. They are not part of the server API documented here, and an accesskey cannot be used as a dashboard bearer token.

Request IDs#

Relay generates a UUID for each HTTP request and returns it in both places below:

http

X-Request-Id: 923d2eb7-361e-4a56-a846-e5fc81065864

json

{
  "meta": {
    "requestId": "923d2eb7-361e-4a56-a846-e5fc81065864"
  }
}

Log this value with your internal request or order ID. Include it when contacting Relay about a failed or unexpected request. You may send your own X-Request-Id, but Relay currently generates the authoritative response request ID.