OAuth connections

Get Connection

Description: Get connection metadata.

Sample success response (200):

{
  "ok": true,
  "connection": {
    "id": "conn_507f1f77bcf86cd799439014",
    "provider": "google",
    "status": "active",
    "identity": {
      "email": "user@example.com"
    },
    "scopes_granted": ["openid", "email", "profile"],
    "expires_at": "2026-07-06T11:00:00.000Z"
  }
}

Common errors: OAUTH_UNAUTHORIZED_APP, connection not found (404)

cURL:

curl "https://api.cliodot.com/oauth/connections/conn_507f1f77bcf86cd799439014" \
  -H "Authorization: Bearer YOUR_APP_API_KEY"

Get Access Token

Description: Fetch the access token for a connection. Auto-refreshes if expired.

Sample success response (200):

{
  "ok": true,
  "access_token": "PROVIDER_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_at": "2026-07-06T11:00:00.000Z"
}

Common errors: OAUTH_UNAUTHORIZED_APP, OAUTH_CONNECTION_REVOKED, OAUTH_PROVIDER_ERROR

cURL:

curl "https://api.cliodot.com/oauth/connections/conn_507f1f77bcf86cd799439014/token" \
  -H "Authorization: Bearer YOUR_APP_API_KEY"

Refresh Connection Token

Description: Force-refresh the access token using the stored refresh token.

Sample success response (200):

{
  "ok": true,
  "connection": {
    "id": "conn_507f1f77bcf86cd799439014",
    "status": "active"
  },
  "access_token": "PROVIDER_ACCESS_TOKEN",
  "expires_at": "2026-07-06T12:00:00.000Z"
}

Common errors: OAUTH_CONNECTION_REVOKED, OAUTH_PROVIDER_ERROR

cURL:

curl -X POST "https://api.cliodot.com/oauth/connections/conn_507f1f77bcf86cd799439014/refresh" \
  -H "Authorization: Bearer YOUR_APP_API_KEY"

Revoke Connection

Description: Revoke the connection at the provider (when supported) and mark it revoked locally.

Request body (optional):

{
  "reason": "user_logged_out"
}

Sample success response (200):

{
  "ok": true,
  "revoked": true
}

Common errors: OAUTH_UNAUTHORIZED_APP, OAUTH_CONNECTION_REVOKED, OAUTH_PROVIDER_ERROR

cURL:

curl -X POST "https://api.cliodot.com/oauth/connections/conn_507f1f77bcf86cd799439014/revoke" \
  -H "Authorization: Bearer YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "user_logged_out" }'

Delete Connection

Description: Hard-delete a connection and its token vault entry.

Sample success response (200):

{
  "ok": true,
  "deleted": true
}

Common errors: OAUTH_UNAUTHORIZED_APP, connection not found (404)

cURL:

curl -X DELETE "https://api.cliodot.com/oauth/connections/conn_507f1f77bcf86cd799439014" \
  -H "Authorization: Bearer YOUR_APP_API_KEY"