Authentication

OrgRelay authenticates to your connector as one company. Four methods are supported; the rules that matter more than the method are tenant mapping, rotation and what happens on revocation.

This page is about OrgRelay calling your system. When staff call OrgRelay from Claude or Codex, they use personal OrgRelay tokens instead, covered in the MCP guide.

#Supported methods

Declare the default in your manifest under auth, for example { "type": "oauth2_client_credentials", "token_url": "https://erp.example/oauth/token", "scopes": ["orders.read"] }. The admin screen pre-fills from it.

#One token is one tenant

This is the rule the self-test tool checks hardest:

1. Decide the tenant from the token, and return only that tenant's data.
2. Never switch tenants because of an id in the request body. A token for company A that asks for customer_id belonging to company B gets not_found, not the record.
3. Integrators who host one connector for several clients should issue one token per client.

The self-test runs every read tool with two tokens and fails if tenant B can see anything tenant A owns. More on this in security requirements.

#Token requirements

• At least 32 random characters. openssl rand -hex 24 gives 48.
• Show the token once in your admin interface, store only a hash.
• HTTPS for anything leaving the LAN. Plain HTTP is acceptable only inside the customer's network.
• No redirects. OrgRelay does not follow them. A reverse proxy that answers 301 to the OrgRelay URL looks like a failure.

On the OrgRelay side, credentials are stored encrypted on the customer's machine, only the last four characters are ever displayed, and they never appear in logs.

#OAuth 2.1 client credentials

OrgRelay posts to your token_url with grant_type=client_credentials, the client ID and secret, and any scopes the admin entered. Your token endpoint returns:

{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600 }

• Access tokens around one hour are typical.
• OrgRelay refreshes before expiry.
• If a call returns 401, OrgRelay fetches a new token once and retries. A second 401 is reported to the owner.

There is no user login step. OrgRelay acts as the company, and the person behind each call is passed separately in orgrelay/actor (see MCP transport).

#Rotation without downtime

Allow two valid tokens per tenant at the same time:

1. Issue a new token in your system.
2. The owner opens the connection in OrgRelay, pastes the new token under credentials (leaving it blank keeps the old one) and clicks Test connection.
3. Once the test passes, revoke the old token.

No calls fail during the switch.

#Revocation

A revoked token must get 401 immediately, on the next call. OrgRelay shows the owner "token rejected" and does not retry in a loop, so revocation is also the fastest way to cut OrgRelay off in an incident.

403 means something different: the token is valid but lacks permission for this tool. Use it when a token is scoped to read-only and someone approved a write. Error codes are listed in the connector spec.

#IP allow-lists

Allow-listing the OrgRelay machine is supported and common. Ask the customer's IT for the outbound IP of the Mac mini (or whatever runs OrgRelay). Inside a LAN that is usually a fixed private address. Across networks, use a VPN or a reverse proxy with its own authentication, never an open endpoint.

#Platform connectors

Connectors in the directory use each platform's own scheme: WooCommerce consumer keys, QuickBooks Online OAuth 2.0 with refresh tokens, Kingdee app credentials. Each connector page lists the exact fields, for example Shopify or QuickBooks Online.

#Common questions

Which method for a new connector? Bearer token on a LAN; OAuth 2.1 client credentials if you already run an OAuth server or need short-lived tokens.

Rotation without downtime? Two valid tokens per tenant, as above.

Redirects? Never followed. Give OrgRelay the final URL.

#Next

• Approvals and write tools: what a token is allowed to trigger.
• Events: the reverse direction, with its own signing secret.
• The company-level security story, for the owner you are working with, is on orgrelay.com/security.
• Platform-specific credentials: Stripe restricted keys, Salesforce OAuth apps, Kingdee app credentials.
• Credentials for APIs you import without code: OpenAPI import and GraphQL import.
• Check your implementation with the self-test tool.

#Related pages

• Quickstart: run a template and pass the self-test in 15 minutes.
• Code templates: download the developer kit and four templates.
• Enterprise patterns: permissions, offboarding and data residency.
• Human-in-the-loop: why approvals live outside the AI client.
• Standard tools: recommended tool names for 14 business domains.
• Third-party MCP: put a vendor's MCP server behind OrgRelay.
• Claude Code: one command with a personal token.