Connect accounts

Every partner API call on this page uses your partner API key as a bearer token, from your servers only. The partner API reference lists each request and response in full.

The partner API is available to approved partners. Revyl turns it on for your platform in each environment and may turn on your customer accounts one at a time. Connecting an account that isn’t turned on answers 403 partner_not_allowed.

export REVYL_API_BASE_URL="https://backend.revyl.ai"
export PARTNER_API_KEY="<your partner key>"

Connect an account

Send your own ID for the customer account, the names to show, and the email of the person enabling the connection:

curl --request POST "${REVYL_API_BASE_URL}/api/v1/partner/connections" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "external_account_id": "acct_123",
    "external_account_name": "Example Workspace",
    "organization_name": "Example Workspace",
    "owner_email": "[email protected]",
    "mode": "auto"
  }'

Field	Meaning
`external_account_id`	Your ID for the account: 1 to 128 letters, digits, `_`, or `-`. Every later call uses it.
`external_account_name`	Your name for the account, shown to the person approving in Revyl.
`organization_name`	The name of a workspace Revyl creates. It’s a display name, not an identity. Revyl may simplify it, and adds a number if the name is taken.
`owner_email`	The email of the person enabling the connection. Send only an address you have verified: when Revyl creates the workspace, it creates this person’s Revyl account as already confirmed and makes them its Owner.
`mode`	`auto` (default) or `link_existing`.

What happens depends on the mode and on whether the email already has a Revyl account:

auto, and the email has no Revyl account: Revyl creates a workspace, makes that person its Owner, and answers 201 with state: "connected", origin: "provisioned", and the connection credential.
auto, and Revyl created a workspace for this account before: Revyl reconnects that workspace and answers 201, even after a disconnect.
auto, and the email already has a Revyl account: Revyl asks for approval and answers 202 with state: "awaiting_approval".
link_existing: Revyl always asks for approval and answers 202.
The account isn’t turned on for your integration: Revyl answers 403 partner_not_allowed.

Connect is safe to repeat for the same account. A retry after a timeout picks up where the first request stopped. If the account is already connected, Revyl answers 409 already_connected with the connection; use Rotate the credential if you lost it.

Wait for approval

A 202 response carries an approval:

{
  "connection": { "external_account_id": "acct_123", "state": "awaiting_approval" },
  "approval": {
    "user_code": "BCDF-GHJK",
    "verification_uri": "https://app.revyl.ai/connect",
    "verification_uri_complete": "https://app.revyl.ai/connect?code=…",
    "expires_in": 604800,
    "interval": 5
  }
}

Revyl emails the request to the person who asked. If they aren’t an Owner or Admin of any of their organizations, Revyl emails the Owners and Admins of up to three of those organizations instead. Show the person user_code and a link to verification_uri_complete; the approver checks that the code in Revyl matches yours. The request expires after expires_in seconds. Revyl sends one reminder three days after the request if no one has decided. Calling connect again for the same person returns the same approval and resends its email at most once every 10 minutes; a different owner_email replaces the request, and the old link stops working. Then poll every interval seconds:

curl --request POST \
  "${REVYL_API_BASE_URL}/api/v1/partner/connections/acct_123/approval/token" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}"

Response	Meaning	Next step
`200`	Approved. The body has the connection and its credential.	Store the credential and stop polling.
`400 authorization_pending`	No one has decided yet.	Keep polling.
`400 slow_down`	You polled too fast.	Add 5 seconds to the interval.
`400 access_denied`	The approver declined.	Stop polling.
`400 expired_token`	The request expired, was replaced, or was already collected.	Connect again.

Revyl delivers the credential once. If you stop polling before you collect it, issue one with Rotate the credential.

Use the connection credential

The credential is an opaque API key for the connected workspace, with expires_at beside it. Revyl returns it only when it’s created, so store it on your servers. Use it like a Revyl API key: send it as a bearer token to the Revyl API, or set it as REVYL_API_KEY for the CLI.

REVYL_API_KEY="<connection credential>" revyl device start --platform ios --app "$APP_ID" --json

Work you start with it runs in the connected workspace, and the customer sees it there.

Rotate the credential

curl --request POST \
  "${REVYL_API_BASE_URL}/api/v1/partner/connections/acct_123/credentials" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}"

Revyl retires the current credential, then issues a new one (201). The credential it replaces keeps working for a short grace period (two hours by default), so work already running on it can finish. A credential replaced by an earlier rotation, and every session credential, stops working at once. Rotate before expires_at, and after you lose a credential.

Mint a session credential

For a short-lived runtime, such as a VM that runs one job, mint a session credential instead of copying the connection credential:

curl --request POST \
  "${REVYL_API_BASE_URL}/api/v1/partner/connections/acct_123/session-credentials" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{ "ttl_seconds": 7200 }'

It acts as the connection until it expires. ttl_seconds is 60 to 14,400 and defaults to 7,200. The response returns credential_id and the secret once. A session credential also ends when you rotate the connection credential or disconnect, and you can revoke one early with DELETE /api/v1/partner/connections/{external_account_id}/session-credentials/{credential_id}. A revoked, expired, or ended session credential answers 401; mint a new one. A 503 means Revyl couldn’t check it; retry.

Invite teammates

For a workspace Revyl created for the account, you can invite people as Members:

curl --request POST \
  "${REVYL_API_BASE_URL}/api/v1/partner/connections/acct_123/invitations" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{ "email": "[email protected]" }'

Revyl sends each address at most one invitation per UTC day. A linked organization answers 403 not_supported_for_connection, because its own admins invite people.

Check and disconnect

GET /api/v1/partner/connections/{external_account_id} returns the account’s state: connected, awaiting_approval, or not_connected. Treat any state you don’t recognize as not usable. To end a connection:

curl --request DELETE \
  "${REVYL_API_BASE_URL}/api/v1/partner/connections/acct_123" \
  --header "Authorization: Bearer ${PARTNER_API_KEY}"

Disconnecting revokes the connection’s credentials and session credentials and stops every live session started with them. App embeds in the workspace keep working until they’re revoked, so revoke yours with DELETE /api/v1/embeds/{embed_id} first. The workspace and its data stay with the customer. It’s safe to repeat: 204 means nothing is left to stop. To open the workspace for a person, see Dashboard links.

Get started

Atlas

Agents

Runtime

Tests

Builds

Frameworks

Integrations

Partners

Security and network

Connect an account

Wait for approval

Use the connection credential

Rotate the credential

Mint a session credential

Invite teammates

Check and disconnect

​Connect an account

​Wait for approval

​Use the connection credential

​Rotate the credential

​Mint a session credential

​Invite teammates

​Check and disconnect

Connect an account

Wait for approval

Use the connection credential

Rotate the credential

Mint a session credential

Invite teammates

Check and disconnect