bluenexus.ai Get API Key

Connection Statuses

Each user connection to an external service has a status that indicates its health. Your app should handle each status appropriately.

Statuses

Status Meaning Can Be Fixed?
active Connection is working normally N/A
expired OAuth tokens have expired Yes — call refresh endpoint
error Connection encountered an error Maybe — try refresh, may need reconnect
revoked User or provider revoked access No — user must reconnect

Checking Connection Status

curl https://api.bluenexus.ai/api/v1/connections \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response:

{
  "data": [
    {
      "id": "conn-abc123",
      "providerId": "google",
      "status": "active",
      "canRefresh": true,
      "metadata": {
        "displayName": "John Doe",
        "email": "john@gmail.com",
        "providerName": "Google Workspace"
      }
    },
    {
      "id": "conn-def456",
      "providerId": "slack",
      "status": "expired",
      "canRefresh": true,
      "metadata": {
        "displayName": "john.doe",
        "providerName": "Slack"
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "hasMore": false }
}

Handling Expired Connections

When a connection is expired, refresh it:

curl -X PUT https://api.bluenexus.ai/api/v1/connections/conn-def456/refresh \
  -H "Authorization: Bearer ACCESS_TOKEN"

If the refresh succeeds, the connection returns to active. If it fails (provider revoked the token), the status may change to error or revoked.

Handling Error and Revoked Connections

  • error: Try refreshing. If that fails, prompt the user to disconnect and reconnect the service.
  • revoked: The user must go through the OAuth flow again for that service. Direct them to the connection management page or initiate a new connection via POST /v1/connections/initiate.

Filtering by Status

# List only active connections
curl "https://api.bluenexus.ai/api/v1/connections?filter[status]=active" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Next Steps