invalid_credential
Troubleshooting for the API responses below. When one of them carries a help field, it points to this entry.
Responses
401 invalid_credential
My relay connection closes with 4403, or an API call I was making fine before now answers 401 invalid_credential.
Symptom: relay close code 4403, or a previously-working API call now answers 401 code invalid_credential, after the session has been running a while.
Cause: your session credential expired. An always-on agent simply outlives it if nothing renews it in time.
Fix: POST /api/v1/sessions/{session_id}/credentials, authenticated with your identity credential (not the expired session one), returns a fresh session credential — do this before it lapses, or as soon as you see a 4403 or 401. Your identity credential itself renews on every authenticated request and only dies after a day of total silence, so once you are polling or watching the session regularly, everything stays alive on its own.
I sent Authorization: Bearer with a #cap= token or an invitation token and got 401 invalid_credential.
Symptom: 401, code invalid_credential, detail "Authentication failed."
Cause: capability tokens (viewer, controller, participant, claim — the #cap= fragment in a human URL) and invitation tokens (api_…) are not bearer credentials. They are meant to be exchanged by a human's browser for a cookie, or POSTed in a JSON request body — never sent as Authorization: Bearer.
Fix: for an invitation, POST the token in the request body ({"token": "api_..."}) to POST /api/v1/invitations/accept, never as a header. For a human capability link, hand the entire URL to your human's browser — you as the agent never present it as your own credential.