Share.Ninja API (1.0.0)

Registers the calling device and issues its session. device_public_key is the device identity and its trust-circle key: the same key refreshes the same agent, a different key creates a new one.

Returns agent_id, name and a one-time WebSocket ticket valid for 30 seconds — connect to GET /ws/connect?ticket=… at once. With response_mode=token the session comes back as access_token and refresh_token, otherwise as cookies. name and nearby_visibility are stored when sent and untouched when omitted; a new device starts at everyone. Sign in with POST /auth/sessions.

Exchanges a refresh token, or an authorization code from the consent flow, for a new access token. The grant type selects the body shape; see TokenRequest.

A refresh token is rotated on every use: the response carries a new one and the token sent stops working. Replaying an already-rotated token past the grace window answers 401 refresh_token_reused and revokes the session, so the client must authenticate again.

Device tokens are issued by POST /auth/agents and user tokens by POST /auth/challenges/{token}; this endpoint only renews them.

Revokes a refresh token per RFC 7009, ending the session it belongs to. Answers 204 whether or not the token was valid, so the response cannot be used to probe a token.

Revokes the refresh token taken from the body, or from the refresh_token cookie when the body carries none, and clears the session cookies.

Returns the details of an authorization request so the client can render the consent screen. There is no client registration: code_challenge is required, and the matching verifier is checked when the code is exchanged.

Records the user's consent decision and returns the redirect URL carrying the authorization code, which POST /auth/token exchanges together with the PKCE verifier. Requires a signed-in user.

The code belongs to the device named by agent_id when it is given — the requesting client's own device, in the same app as the approving session — and to the approving device otherwise; the exchanged session is minted for that device.

Deprecated: use GET /users/me/devices, which returns the same sessions attached to their device cards.

Returns the authenticated user's sessions that are not revoked. Each carries its id for selective revocation, the address and user agent it was created with, when it was created and last used, and whether it is the calling session.

Starts authentication for an email address. An address with no account is signed up by this very call; there is no separate registration step.

The response always carries a challenge listing the account's sign-in methods, in a shape identical for a known and an unknown address, so registered addresses cannot be enumerated. No session is issued here, and no email code is sent unless email_code is the only method: otherwise request it with POST /auth/challenges/{token}/code once the user picks it. An account that removed its email_code factor lists no such entry; a lost password is reset through POST /auth/recovery.

Verify one method with POST /auth/challenges/{token}; the response completes the login or lists the second step.

Revokes the caller's own session together with its refresh tokens, and clears the session cookies.

Revokes the named session and its refresh tokens, signing out the device that holds it.

Revokes every other session of the current user: every other signed-in device is signed out, while the calling session stays signed in and keeps its credential.

Always answers 403 challenge_required: a challenge is never minted out of band.

To confirm a sensitive operation, call that operation without confirmation. Its 403 challenge_required refusal carries a challenge bound to that exact call; verify it with POST /auth/challenges/{token} and retry the operation with the token in the X-Auth-Challenge header.

Verifies one entry of the challenge named by token: a sign-in method first, then — when the response lists second_factors — one of those. The call needs a registered device: its access credential names the device the session is minted on.

For a login or signup, the step that completes it issues the session. With response_mode=token it comes back as access_token and refresh_token, otherwise it is set as cookies.

For a step-up, complete: true means the path token is now spendable: retry the operation with it in the X-Auth-Challenge header.

A wrong credential, or a factor_id the account does not have, answers 401 invalid_credentials and counts against the attempt limit.

A recovery with two-step verification on whose second step nothing is left to answer is refused with 409 no_second_factor.

Sends the code for one code-delivering entry of the challenge named by token — the email_code entry by email, an sms entry by text — a fresh one on every call, so it also resends. Each send draws on the address's code budget. An entry the challenge does not list at its current step, or one that delivers no code, answers factor_not_allowed.

Starts a password recovery for an email address and mails its code at once. The response is a challenge whose only entry is email_code, in a shape identical for a known and an unknown address; an unknown one gets no mail. Verify the code with POST /auth/challenges/{token}: with two-step verification on, the second step follows as for a login, without the password: any other confirmed factor or a recovery code. With nothing left to answer it, verify refuses the recovery (no_second_factor). A completed recovery issues no session; it answers complete with the token that POST /auth/recovery/{token}/password spends.

Sets the account's password from a completed recovery challenge, replacing the existing one, and ends every session of the account. The token is spent by this call. An unknown, unverified or already spent token answers invalid_challenge_token; one past its time, challenge_expired. A completed recovery opens no session: the client signs in with the new password.

Returns the SSO providers enabled for this deployment, each with the label to show on its sign-in button.

Returns the provider's authorization URL for the client to open, and sets the state cookie the callback checks. The provider then redirects to /auth/sso/{provider}/callback with an authorization code.

The call must carry the calling device's access credential — the SSO login binds to that device — and answers 401 without one. An expired access token is still accepted here, because the round trip through the provider can outlast its 15-minute lifetime.

Completes the provider's redirect: checks state against the state cookie, exchanges the code with the provider, and establishes the session on the device the flow started from. Session cookies are set either way; with response_mode=token the profile is returned as JSON instead of the redirect.

Completes the flow for a provider that posts the callback as form data instead of redirecting with query parameters, which is how Apple Sign-In returns. Otherwise it behaves like the GET callback.

Exchanges an ID token that a native app obtained from the Google or Apple sign-in SDK for a session, creating the account when the identity is new. The session is set as cookies and the body returns the profile with is_new_user. The call must carry the calling device's access credential; the session binds to that device.

An identity linked to no account whose verified address already belongs to one is refused with 409 email_already_in_use.

Returns every authentication factor on the caller's account with its type and confirmation state, alongside available_types: the types the account may enroll now — what this deployment accepts, and email_code only while the account has none. A factor takes part in login once confirmed.

Creates a factor on the caller's account and returns what is needed to finish setup. A verified challenge in X-Auth-Challenge is required, unless this session confirmed another factor change within the deployment's step-up window.

The factor takes no part in login until it is confirmed. A password arrives confirmed, creating it being the proof, replaces the account's existing one and signs every other session of the account out — the one that set it stays; email_code arrives confirmed too, the address being the account's own. TOTP returns the shared secret and provisioning URI once, here; sms sends a code; webauthn returns registration options. Confirm those with POST /users/me/auth/factors/{factor_id}/confirm.

Returns one factor of the caller's own account: its type, confirmation state and what may be changed about it. A factor id belonging to another account reads as factor_not_found.

Deletes one of the caller's own factors. A verified challenge in X-Auth-Challenge is required; without one the call answers 403 challenge_required with a challenge bound to this deletion, unless this session confirmed another factor change within the deployment's step-up window with a factor other than this one.

The account's last sign-in method — password, passkey or email code — will not go (cannot_delete_last_sign_in_method). A deletion that leaves the account with a single confirmed factor while two-step verification is on switches it off, voids the recovery codes and says so in the response.

Proves a newly enrolled factor works and marks it confirmed. Send the code from the authenticator app, the email or the SMS as {"code": "123456"}, or the browser's registration result as webauthn_response. A password factor is confirmed when it is created, so it does not use this call.

A confirmed factor takes part in login from then on, at the step its type decides. A wrong credential answers invalid_code, and a factor that is already confirmed answers factor_already_confirmed.

Turns two-step verification on for the caller's account and returns its recovery codes, shown this once. From now on a sign-in by password or email code is followed by any other confirmed factor of the account; a passkey or SSO sign-in completes on its own.

Needs at least two confirmed factors (second_factor_required) and a verified challenge in X-Auth-Challenge, unless this session confirmed another factor change within the deployment's step-up window. Already on answers two_step_already_enabled.

Turns two-step verification off and voids the recovery codes; the factors stay enrolled. A verified challenge in X-Auth-Challenge is required, unless this session confirmed another factor change within the deployment's step-up window. Already off answers two_step_not_enabled.

How many recovery codes are left unused. Zero, with no generated_at, while two-step verification is off.

Issues a fresh set of recovery codes, shown this once, and voids the previous set. Needs two-step verification on (two_step_not_enabled) and a verified challenge in X-Auth-Challenge, unless this session confirmed another factor change within the last five minutes.

Updates the caller's own profile and returns it in full. display_name renames the account. avatar carries a base64 data URL to upload a new image, an empty string to drop the uploaded one, and is left out to keep the current one. A request that changes neither is rejected.

The email address is changed through POST /users/me/email/change, not here. An image larger than 5 MB answers 413 avatar_too_large; an unsupported format or one outside the accepted pixel range answers 400.

Deletes the caller's account together with the workspaces it owns and everything anchored to them, and ends every session on every device. Irreversible.

Billing settles first: every subscription must already be inactive at the provider and no billing operation may be left pending, so scheduling a cancellation is not enough. An account that has not settled answers 409 billing_cancellation_required; a workspace the caller still owns and cannot take along answers 409 user_owns_workspaces, so hand it over before retrying.

An identity linked through Sign in with Apple is revoked at Apple before the account goes; if Apple refuses, the deletion fails and can be retried.