Authentication Endpoints — Login, Profile, and OAuth

These endpoints handle account management: logging in, viewing your profile, rotating tokens, verifying your email, and linking OAuth providers. They are distinct from inference — you do not use a JWT to call models. API keys for inference (sk-...) are created and managed in the Piramyd dashboard.

There is no public account registration endpoint. Accounts are created at dash.piramyd.cloud through the onboarding flow — not via the API. All endpoints below require an existing account.

Endpoint Reference

Method	Path	Auth Required	Purpose
`POST`	`/v1/auth/token`	None	Login with username/email + password, returns JWT
`GET`	`/v1/auth/me`	JWT	Current user profile
`DELETE`	`/v1/auth/me`	JWT	Delete your own account
`POST`	`/v1/auth/refresh`	JWT	Rotate refresh token, returns new token pair
`POST`	`/v1/auth/logout`	JWT	Revoke your refresh token
`POST`	`/v1/auth/email-verification/send-code`	JWT	Send an email verification code to your address
`POST`	`/v1/auth/email-verification/verify-code`	JWT	Verify your email using the sent code
`GET`	`/v1/auth/oauth/{provider}/start`	None	Start an OAuth sign-in flow (e.g. `github`)
`GET`	`/v1/auth/oauth/{provider}/connect/start`	JWT	Link an OAuth provider to your existing account
`GET`	`/v1/auth/oauth/{provider}/callback`	None	OAuth redirect callback
`POST`	`/v1/auth/oauth/exchange`	None	Exchange an OAuth authorization code for tokens

POST /v1/auth/token

Exchange your credentials for a JWT access token and refresh token. This is your entry point for all subsequent account management calls. Base URL: https://api.piramyd.cloud

Request Body

string

required

Your account username or the email address registered at dash.piramyd.cloud.

string

required

Your account password.

Response

string

A short-lived JWT. Pass this as Authorization: Bearer <access_token> on all account management requests.

string

A longer-lived token. Use it with POST /v1/auth/refresh to obtain a new token pair without re-entering your password.

string

Always "bearer".

Example

import httpx

resp = httpx.post(
    "https://api.piramyd.cloud/v1/auth/token",
    json={
        "username_or_email": "you@example.com",
        "password": "your-password",
    },
)

data = resp.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]

print(f"Token type: {data['token_type']}")
print(f"Access token: {access_token[:20]}...")

curl -s -X POST https://api.piramyd.cloud/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username_or_email": "you@example.com", "password": "your-password"}'

GET /v1/auth/me

Returns the profile for the currently authenticated account. Use this to confirm token validity or retrieve account details such as your user ID, email, and verification status. Base URL: https://api.piramyd.cloud

Headers

string

required

Bearer <access_token> — the JWT obtained from POST /v1/auth/token.

Example

import httpx

access_token = "eyJ..."  # from /v1/auth/token

resp = httpx.get(
    "https://api.piramyd.cloud/v1/auth/me",
    headers={"Authorization": f"Bearer {access_token}"},
)

profile = resp.json()
print(profile)

curl -s https://api.piramyd.cloud/v1/auth/me \
  -H "Authorization: Bearer eyJ..."

DELETE /v1/auth/me

Permanently deletes your account. This action is irreversible — all associated data, including API keys, will be removed.

Deleting your account cannot be undone. All API keys tied to the account will be invalidated immediately. Make sure you have migrated any active integrations before proceeding.

Base URL: https://api.piramyd.cloud

Headers

string

required

Bearer <access_token> — JWT from POST /v1/auth/token.

POST /v1/auth/refresh

Rotate your token pair. Submit your current refresh token to receive a new access_token and refresh_token. The old refresh token is revoked after a successful call. Base URL: https://api.piramyd.cloud

Request Body

string

required

The refresh token returned by POST /v1/auth/token or a previous POST /v1/auth/refresh call.

Response

string

A new short-lived JWT.

string

A new refresh token. Store this and discard the old one immediately.

string

Always "bearer".

Example

import httpx

resp = httpx.post(
    "https://api.piramyd.cloud/v1/auth/refresh",
    json={"refresh_token": "your-current-refresh-token"},
)

tokens = resp.json()
new_access_token = tokens["access_token"]
new_refresh_token = tokens["refresh_token"]

POST /v1/auth/logout

Revoke the current refresh token, ending the session. The access token will continue to work until it expires naturally, but it can no longer be refreshed. Base URL: https://api.piramyd.cloud

Headers

string

required

Bearer <access_token> — JWT from POST /v1/auth/token.

Email Verification

POST /v1/auth/email-verification/send-code

Sends a verification code to the email address on your account. Call this when your account email shows as unverified.

POST /v1/auth/email-verification/verify-code

Submit the code you received to mark your email as verified.

string

required

The verification code from the email sent by /send-code.

Both endpoints require Authorization: Bearer <access_token>.

OAuth

Piramyd supports OAuth-based sign-in and account linking. Replace {provider} with a supported provider slug such as github.

GET /v1/auth/oauth//start

Redirects your user to the OAuth provider’s authorization page to begin a sign-in flow. No auth required — redirect your browser or user agent to this URL.

GET /v1/auth/oauth//connect/start

Same as /start but links the OAuth provider to an existing account rather than creating a new session. Requires Authorization: Bearer <access_token>.

GET /v1/auth/oauth//callback

The redirect target registered with the OAuth provider. The API handles the callback and exchanges the authorization code internally. You typically do not call this directly.

POST /v1/auth/oauth/exchange

Exchange an OAuth authorization code for a Piramyd token pair. Use this in server-side or native OAuth flows where you handle the callback yourself.

string

required

The authorization code returned by the OAuth provider.

string

required

The OAuth provider slug (e.g. github).

For inference requests — calling models via /v1/chat/completions, /v1/responses, or any other model endpoint — use your API key (sk-...), not a JWT. JWTs are only accepted on /v1/auth/... account management endpoints. Create and manage API keys at dash.piramyd.cloud.

Inference

Models

Web Intelligence

Account

Authentication Endpoints — Login, Profile, and OAuth

Endpoint Reference

POST /v1/auth/token

Request Body

Response

Example

GET /v1/auth/me

Headers

Example

DELETE /v1/auth/me

Headers

POST /v1/auth/refresh

Request Body

Response

Example

POST /v1/auth/logout

Headers

Email Verification

POST /v1/auth/email-verification/send-code

POST /v1/auth/email-verification/verify-code

OAuth

GET /v1/auth/oauth//start

GET /v1/auth/oauth//connect/start

GET /v1/auth/oauth//callback

POST /v1/auth/oauth/exchange

​Endpoint Reference

​POST /v1/auth/token

​Request Body

​Response

​Example

​GET /v1/auth/me

​Headers

​Example

​DELETE /v1/auth/me

​Headers

​POST /v1/auth/refresh

​Request Body

​Response

​Example

​POST /v1/auth/logout

​Headers

​Email Verification

​POST /v1/auth/email-verification/send-code

​POST /v1/auth/email-verification/verify-code

​OAuth

​GET /v1/auth/oauth//start

​GET /v1/auth/oauth//connect/start

​GET /v1/auth/oauth//callback

​POST /v1/auth/oauth/exchange

Endpoint Reference

POST /v1/auth/token

Request Body

Response

Example

GET /v1/auth/me

Headers

Example

DELETE /v1/auth/me

Headers

POST /v1/auth/refresh

Request Body

Response

Example

POST /v1/auth/logout

Headers

Email Verification

POST /v1/auth/email-verification/send-code

POST /v1/auth/email-verification/verify-code

OAuth

GET /v1/auth/oauth//start

GET /v1/auth/oauth//connect/start

GET /v1/auth/oauth//callback

POST /v1/auth/oauth/exchange