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.

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

Set up with an agent

Paste one prompt and your coding agent does the rest.

Copy setup promptPreview prompt

Setup prompt

Copy

Add Revyl partner connections to this backend.

Read https://docs.revyl.com/partners/connect.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

The partner API is for approved partners. Keep the partner API key on the server, in an environment variable or this project's secret store, never in client code or a commit.

You're done when the backend can connect a test account, collect its connection credential, and disconnect it.

Ask me before anything that needs my login or approval.

Connect an accountCopy Anchor Link

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": "alex@example.com",
    "mode": "auto"
  }'

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 approvalCopy Anchor Link

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}"

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

Use the connection credentialCopy Anchor Link

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 credentialCopy Anchor Link

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 credentialCopy Anchor Link

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 teammatesCopy Anchor Link

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": "sam@example.com" }'

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 disconnectCopy Anchor Link

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.