Accounts, auth & tokens

Signing in

Your account is a single global identity, your email address and a password, that follows you across every organization you belong to. You sign in once and Elliptic keeps you in a secure session, so you do not have to re-enter your password on every visit. When you create an account, Elliptic hashes your password with argon2id and never stores the plaintext. Passwords are 8 to 128 characters.

On the hosted instance you sign in at elliptic.sh. When you submit your email and password, Elliptic verifies the credentials and starts a session for you.

Email verification at sign-up

When the instance is configured to send email, a brand-new account starts unverified: Elliptic emails you a 6-digit code, and you confirm it before you can sign in. If your instance has no mail configured, accounts are verified automatically and you can sign in right away. The account-creation walkthrough lives in Overview & Getting Started. This page focuses on how sign-in and tokens work once you have an account.

Session cookies

A successful login issues two short JSON Web Tokens and sets them as cookies on your browser: an access token that authorizes each request, and a longer-lived refresh token used to get a new access token when the first one expires. Both cookies are httpOnly, so page scripts cannot read them, and both are SameSite=Lax. On the hosted instance they are also marked Secure, so they only travel over HTTPS. You stay signed in until the refresh token expires or you log out.

Refresh and logout

When your access token expires, the web app refreshes the pair automatically: on a 401 it calls the refresh endpoint once, then retries your request, so the rotation is invisible to you. Programmatic clients can drive this themselves. The refresh endpoint accepts the refresh token either from the cookie or from the request body, and returns a new access and refresh token. Logging out clears both cookies, ending the session on that device.

Three ways the API accepts your credentials

Every authenticated request resolves your identity from one of three places, checked in this order. The first one present wins:

If the credential starts with cos_pat_, Elliptic treats it as a personal access token and resolves it through the owning user. Otherwise it decodes it as a session access token. Either way the request runs as you, with exactly your permissions.

You can browse the full REST surface, with every endpoint and its request and response shapes, at /api/v1/docs on your instance.

Two-factor authentication

Two-factor authentication (2FA) adds a second step to sign-in: after your password, you enter a rotating 6-digit code from an authenticator app. Elliptic uses TOTP (time-based one-time passwords), the open standard supported by Google Authenticator, 1Password, Authy, and similar apps. Codes rotate every 30 seconds, and Elliptic tolerates one period of clock drift in either direction, so a code that just turned over still works.

Turning it on

1. 1
   Start setup

   Begin enrollment from your account security settings. Elliptic generates a fresh secret and returns it along with an otpauth:// URI you can render as a QR code.
2. 2
   Scan the QR code

   Open your authenticator app and scan the QR code, or paste the secret by hand. The app starts showing a new 6-digit code every 30 seconds, labeled Elliptic with your email.
3. 3
   Confirm a code to enable

   Enter the current code to finish. Elliptic verifies it against the pending secret and only then switches 2FA on. This proves your app is set up correctly before you depend on it.

Once 2FA is enabled, signing in takes one extra field. You submit your email and password as usual, and Elliptic tells the login screen that a code is required. You enter the current code from your app, and the session starts. Without a valid code, login does not complete.

To turn 2FA off, confirm one more current code. Elliptic verifies it, then disables two-factor and discards the stored secret, so re-enabling later starts a fresh enrollment.

Your profile

Your profile carries the basics of your identity: your full name, your sign-in email, and your preferred locale (which defaults to en). You can update your name and locale from your profile settings at any time. Your email is the stable handle for your account and is shown read-only there.

The account is global. The same name, email, and 2FA settings apply everywhere you work, across every organization you are a member of. Switching organizations changes the workspace around you, not who you are. Your role and permissions, by contrast, are set per organization, which is covered in Organizations & Members.

Personal access tokens

A personal access token (PAT) lets a script, a CI job, or any tool call the Elliptic API as you, without your password and without a browser session. Every token begins with the prefix cos_pat_ so it is easy to spot, and you send it exactly like any other credential, as a Bearer token or in the x-api-key header.

Minting a token

Create a token from your access-tokens settings. You give it a name (and an optional description) so you remember what it is for, and you can set an optional expiry between 1 and 365 days. With no expiry it lasts until you revoke it.

Listing, regenerating, and revoking

• List shows your active tokens with their metadata only: name, description, a short prefix, when each was created, when it was last used, and any expiry. The secret itself is never shown again.
• Regenerate rotates a token's secret in place. The name, description, and expiry stay, the old value stops working immediately, and you get a fresh plaintext to copy once. Use this to rotate a key without re-wiring everything that references it.
• Revoke permanently disables a token. Any request using it is rejected from that moment on.

A token only ever works while your account is active. Tokens carry your identity, so anything you can reach in the API, the token can reach too. Scope them by purpose, give each automation its own, and revoke the ones you no longer use.

OAuth bot apps

When you want an automation to run on its own, on a schedule or from another service, rather than carrying a token you pasted by hand, you register an OAuth app. This is a confidential client-credentials application: it holds a client id and a secret, and it exchanges them for a token that acts as you. In agent-native terms, this is how a background agent earns its own credentials to operate the same surfaces you do.

1. 1
   Register the app

   Create the app with a name. Elliptic returns a client_id (it looks like app-<random>) and a client_secret that begins with cos_secret_. The secret is shown once, just like a personal access token, so copy it immediately.
2. 2
   Exchange credentials for a bot token

   Your automation posts grant_type=client_credentials with its client_id and client_secret to the token endpoint. Elliptic validates the pair and returns a bot token that acts as you, the app's owner. The bot token is itself a personal access token, named bot:<app name>, minted on your account.
3. 3
   Call the API as the bot

   Use the returned token like any other credential, as a Bearer token. Every call runs with your identity and your permissions.

curl -X POST https://elliptic.sh/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=app-xxxxxxxx \
  -d client_secret=cos_secret_xxxxxxxx

You can list your registered apps and revoke any of them. Revoking an app stops it from minting new bot tokens. Because a bot token acts as the owner, treat the client secret with the same care as a password.

Social and per-org sign-in methods

Beyond email and password, Elliptic can sign you in with Google or GitHub. Pick the provider on the login screen, approve access on Google's or GitHub's side, and you land back signed in. The first time you sign in this way, Elliptic provisions your account automatically from the verified email the provider returns (just-in-time provisioning), so there is no separate registration step.

Social providers appear on the login screen only when the instance has been configured with the relevant client credentials. With no credentials set, the Google and GitHub buttons are hidden and email and password remain the way in.

Choosing what your org allows

An admin or owner can set which sign-in methods their organization records as allowed, from the sign-in providers settings. These are stored per organization: