Authentication

How to obtain and use tokens to authenticate Hyperspeed API requests.

Login

Exchange email and password for a JWT access token and a refresh token.

POST /api/v1/auth/login

Request body

email · string · required

The user’s email address.

password · string · required

The user’s password.

Example

curl -X POST https://your-hostname/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "s3cr3tpassword"}'

Response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
  "token_type": "Bearer",
  "expires_in": 900
}

access_token · string

JWT access token. Valid for 900 seconds (15 minutes).

refresh_token · string

Opaque token used to obtain a new access token without re-entering credentials.

token_type · string

Always "Bearer".

expires_in · integer

Access token lifetime in seconds (900).

signup_pending · boolean

Present and true when the account is awaiting admin approval (open-signup flow only).

Using the token

Pass the access token in the Authorization header on every subsequent request:

curl https://your-hostname/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5..."

Refreshing the token

When the access token expires, use the refresh token to get a new pair without re-entering credentials.

POST /api/v1/auth/refresh

refresh_token · string · required

The refresh token received at login.

curl -X POST https://your-hostname/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2..."}'

The response is the same shape as /auth/login. The old refresh token is invalidated immediately.

Logout

Invalidate a refresh token server-side.

POST /api/v1/auth/logout

refresh_token · string · required

The refresh token to revoke.

Returns 204 No Content on success.

Service account tokens

Service accounts are used for programmatic or AI staff access. Their tokens are prefixed with sa_ and are not JWTs — they authenticate via the same Authorization: Bearer header. A service account token is returned once when the service account is created and is not recoverable afterward. See Service Accounts for creation details.

Use a service account token exactly like a user JWT:

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces \
  -H "Authorization: Bearer sa_4a7f3c..."

Service account tokens do not expire unless explicitly revoked. Store them securely.

Common errors

Status	Error message	Cause
401 Unauthorized	"invalid credentials"	Wrong email or password
401 Unauthorized	"unauthorized"	Missing or expired token on a protected route
403 Forbidden	"signups_disabled"	Registration is disabled on this instance