Convex

Convex connects with a team access token created in the Convex dashboard. A team access token is scoped to exactly one team, so one token connects one team. Tokens are encrypted before they are stored, and the agent never sees them.

1. Open the Convex dashboard, go to Team Settings → Access Tokens.
2. Click Create access token and copy the token value.
3. Paste the token into Praxen Inc.
4. Praxen Inc. validates the token and starts syncing.

Praxen Inc. discovers your projects and, within each one, its cloud deployments: the production deployment plus any preview, development, and custom deployments, with their regions, URLs, and deployment classes.

Team access tokens grant management access to the team. Sync reads your projects and deployments with the team token. When the agent or background monitoring reads a deployment's function logs or metrics, Praxen Inc. mints a short-lived deploy key scoped to just that read (log view or metric view), uses it for the one call, and deletes it immediately after, so each key lives only as long as the read it serves. Everything Praxen Inc. reads sits on the management surface: project and deployment listings, function logs, and deployment metrics.

Troubleshooting

"Not a team access token" error

• Project-scoped tokens and deploy keys cannot list the team's projects; create the token under Team Settings → Access Tokens.
• Check that the token has not been deleted in the Convex dashboard.

Missing resources

• Local deployments run on individual developer machines and are deliberately not synced.
• A project created without a deployment shows no deployments until the first deploy.
• Trigger a manual sync to refresh sooner than the next scheduled pass.

Audit logs

• Convex gates its audit log API behind paid plans. On a free team, audit log reads return a clear error and agents fall back to function logs and the context graph.

Disconnecting

Disconnect the account in Praxen Inc., then delete the access token from your Convex team settings.

Connecting Convex needs no browser: the same endpoint the console calls fits in a CI job. One authenticated POST creates the connection and starts the first sync.

Prerequisites

• A Praxen Inc. API key with the cloud_accounts:write and cloud_accounts:read scopes. See API keys and OAuth.
• Your workspace ID, which starts with ws_. Read it from GET /v1/workspaces with the same key.
• A Convex team access token from Team Settings → Access Tokens.

Create the connection

curl -X POST https://api.getpraxen.app/v1/cloud_accounts \
  -H "x-api-key: $PRAXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "convex",
    "workspaceId": "ws_0abc123",
    "token": "<team-access-token>"
  }'

A team access token is scoped to exactly one team, so one call connects one team.

The response lists what was connected, with the first sync already running. Trimmed to the two fields the rest of the flow reads:

{
  "success": true,
  "result": {
    "provider": "convex",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

An account that is already connected lands in failures instead of accounts, so repeating the call never duplicates a connection.

Wait for the first sync

Poll each returned account by its id until status reaches ready (new on registration, syncing while resources stream in):

until [ "$(curl -s "https://api.getpraxen.app/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $PRAXEN_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

Give the loop a deadline so a failed connect fails the job instead of hanging it. Once the account is ready, its resources are in the topology and Praxen Inc. has started its first check.

Disconnect from the API

Deleting the connection stops every sync and check and deletes the credentials Praxen Inc. held. The call needs the cloud_accounts:delete scope:

curl -X DELETE "https://api.getpraxen.app/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $PRAXEN_API_KEY"

Then revoke the Convex credential on the provider side, as described under Disconnect below.