Create a connect link

A hosted link that connects one integration for the end user. Send them to url: a page that names your workspace, then the provider’s consent for an OAuth integration, or a form where they paste their own key for an API-key integration (checked with the provider and stored encrypted; you never see it). Afterwards the browser goes to redirectUrl with anlyon_status (pending_confirmation, connected, declined or error), integration, and, while the grant waits for confirmation, anlyon_flow. The end-user id is never in that URL. Confirm the flow from your server with POST /api/v2/end-users/{endUserId}/connections/confirm.

A redirect is required: redirectUrl must fall under one of the environment’s allowed redirect URLs (exact origin and path prefix), or the environment’s default redirect URL is used; with neither, the answer is 400 REDIRECT_URL_REQUIRED. Only an environment with confirmation off may leave it out: the end user then sees Anlyon’s own page, and the account is theirs at once. The link works once, for 10 minutes; a key link takes up to 5 refused keys before it is used up. At most 10 links per minute per end user, and 300 per environment.

An OAuth integration Anlyon does not offer through its own app, or whose app this deployment does not have, is connected through the environment’s own app: add it with PUT /api/v2/environments/{environmentId}/oauth-apps/{integration}. Until then the answer is 400 OWN_OAUTH_APP_REQUIRED.

POST/api/v2/end-users/{endUserId}/connect-links

Authorization

AuthorizationBearer token (Anlyon API key) · headerrequired

Workspace API key sent as Authorization: Bearer <key>.

better-auth.session_tokenAPI key · cookierequired

Browser session used by dashboard-only operations.

Path parameters

endUserIdstringrequired

Your own id for the end user. 1 to 128 characters of letters, digits and . _ : @ -. URL-encode it.

min length 1 · max length 128 · matches ^[A-Za-z0-9._:@-]{1,128}$

Header parameters

X-Request-Idstring

Optional caller correlation ID. Unsafe or oversized values are replaced.

max length 128

Anlyon-End-Userstring

The end user this call acts for: your own id for them, 1 to 128 characters of letters, digits and . _ : @ -. Accepted only with an API key, which stays on your server; a session or an OAuth token that sends it is refused. A key created with endUserRequired must send it on every action call (400 END_USER_REQUIRED). On an /end-users/{endUserId} route it must name the same end user as the path.

min length 1 · max length 128 · matches ^[A-Za-z0-9._:@-]{1,128}$

Request body

requiredapplication/json

integrationstringrequired

An OAuth integration from the catalogue.

matches ^[a-z][a-z0-9-]{0,63}$

redirectUrlstring

Where the browser goes when consent ends. Must fall under one of the environment's allowed redirect URLs. Defaults to the environment's default redirect URL.

max length 2048

Responses

201

The link.

successbooleanrequired

Allowed:true

dataobjectrequired

Show properties

urlstring<uri>required

Send the end user here. Works once

expiresAtstring<date-time>required

integrationstringrequired

400

Bad Request - Invalid input data

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

How to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

401

Unauthorized - Invalid or missing API key

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

403

Authenticated credential lacks the required scope or workspace access.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

404

Not Found - Resource does not exist

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

429

Too Many Requests - Rate limit exceeded. A workspace's API requests are limited per minute and per UTC clock hour by plan; Retry-After says when to try again, and an hourly refusal names the limit and when the count resets. Successful responses carry the same limits in X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (the minute) and X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour, X-RateLimit-Reset-Hour (the hour).

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

501

Connected accounts are not set up on this deployment (CONNECTIONS_UNAVAILABLE). A missing OAuth app is a 400 OWN_OAUTH_APP_REQUIRED instead.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (Anlyon API key)Remember on this deviceInclude my values in samples

Parameters

X-Request-IdheaderOptional caller correlation ID. Unsafe or oversized values are replaced.endUserIdpath*Your own id for the end user. 1 to 128 characters of letters, digits and `. _ : @ -`. URL-encode it.Anlyon-End-UserheaderThe end user this call acts for: your own id for them, 1 to 128 characters of letters, digits and `. _ : @ -`. Accepted only with an API key, which stays on your server; a session or an OAuth token that sends it is refused. A key created with `endUserRequired` must send it on every action call (`400 END_USER_REQUIRED`). On an /end-users/{endUserId} route it must name the same end user as the path.

Bodyapplication/json

integrationstring*An OAuth integration from the catalogue.redirectUrlstringWhere the browser goes when consent ends. Must fall under one of the environment's allowed redirect URLs. Defaults to the environment's default redirect URL.

Request

curl -X POST 'https://api.anlyon.com/api/v2/end-users/string/connect-links' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "integration": "gmail",
  "redirectUrl": "https://app.example.com/settings/connections"
}'

const response = await fetch("https://api.anlyon.com/api/v2/end-users/string/connect-links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"integration\": \"gmail\",\n  \"redirectUrl\": \"https://app.example.com/settings/connections\"\n}"
});

import requests

response = requests.post(
    "https://api.anlyon.com/api/v2/end-users/string/connect-links",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"integration\": \"gmail\",\n  \"redirectUrl\": \"https://app.example.com/settings/connections\"\n}",
)

Response

{
  "success": true,
  "data": {
    "url": "http://example.com",
    "expiresAt": "2019-08-24T14:15:22Z",
    "integration": "gmail"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "url": "Invalid URL format"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}