Skip to main content

​
Authentication

NeoSC API supports multiple authentication methods:
  • Email/Password - Traditional registration and login
  • SSO via Zitadel - OIDC-based single sign-on
  • Token-based - Bearer token authentication

​
Authentication Flow

  1. Register a new user or login with existing credentials
  2. Receive an access token in the response
  3. Include the token in the Authorization header for all subsequent requests

​
Register User

curl -X POST https://your-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword",
    "name": "John Doe",
    "organization": "Acme Corp"
  }'

​
Request Body

​
email
string
required
User’s email address (must be unique)
​
password
string
required
User’s password (will be hashed using SHA-256)
​
name
string
required
User’s full name
​
organization
string
Organization name (defaults to “Default Organization”)

​
Response

​
access_token
string
Bearer token for authentication (32-byte URL-safe token)
​
token_type
string
Always “bearer”
​
user
object
User object containing profile information
Response Example
{
  "access_token": "xK9mP2nQ4rS6tU8vW0xY2zA4bC6dE8fG0hI2jK4lM6nO8pQ0rS2tU4vW6xY8zA0b",
  "token_type": "bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "organization": "Acme Corp",
    "role": "user",
    "mfa_enabled": true
  }
}

​
Login

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword"
  }'

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Response

Returns the same AuthToken structure as registration.

​
Error Responses

​
401
error
Invalid credentials - Email not found or password incorrect

​
SSO Login (Zitadel OIDC)

curl -X POST https://your-domain.com/api/auth/sso \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "zitadel-access-token",
    "profile": {
      "sub": "123456789",
      "email": "[email protected]",
      "name": "John Doe",
      "picture": "https://example.com/avatar.jpg"
    },
    "provider": "zitadel",
    "roles": ["user", "developer"],
    "groups": ["engineering"]
  }'

​
Request Body

​
access_token
string
required
Zitadel access token from OIDC flow
​
profile
object
required
OIDC user profile containing email, name, sub, etc.
​
provider
string
SSO provider name (defaults to “zitadel”)
​
roles
array
User roles from Zitadel (admin role auto-detected)
​
groups
array
User groups from Zitadel
​
id_token
string
Optional OIDC ID token

​
Role Detection

The API automatically assigns the admin role if:
  • Any role contains “admin”, “administrator”, or equals “owner”
  • Any group contains “admin”
Otherwise, the user role is assigned.

​
Token Exchange

Exchange an authorization code for tokens (used to avoid CORS issues). 
curl -X POST https://your-domain.com/api/auth/token-exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code",
    "code_verifier": "pkce-code-verifier",
    "redirect_uri": "https://your-app.com/callback",
    "provider": "zitadel_onprem"
  }'

​
Request Body

​
code
string
required
Authorization code from OIDC flow
​
code_verifier
string
required
PKCE code verifier
​
redirect_uri
string
required
OAuth redirect URI
​
provider
string
“zitadel_onprem” or “zitadel_cloud” (defaults to “zitadel_onprem”)
​
authority
string
Optional Zitadel authority URL override
​
client_id
string
Optional client ID override

​
Get Current User

Retrieve the currently authenticated user’s profile. 
curl https://your-domain.com/api/auth/me \
  -H "Authorization: Bearer your-token-here"

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "John Doe",
  "organization": "Acme Corp",
  "role": "user",
  "mfa_enabled": true
}

​
Get Current User

Retrieve the profile of the currently authenticated user. 
curl https://your-domain.com/api/auth/me \
  -H "Authorization: Bearer your-token-here"

​
Response

Returns the authenticated user’s profile: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "John Doe",
  "organization": "Acme Corporation",
  "role": "user",
  "mfa_enabled": true
}
This endpoint is useful for validating tokens and retrieving user information for the frontend.

​
Logout

Invalidate the current authentication token. 
curl -X POST https://your-domain.com/api/auth/logout \
  -H "Authorization: Bearer your-token-here"

​
Response

{
  "message": "Logged out successfully"
}

​
Using the Token

Include the access token in all authenticated requests: 
curl https://your-domain.com/api/workspaces \
  -H "Authorization: Bearer your-token-here"

​
Token Format

Tokens are 32-byte URL-safe strings generated using Python’s secrets.token_urlsafe(32).
Security Note: In production, tokens are stored in-memory. Consider using Redis or a database for distributed systems.

​
Error Responses

​
400
error
Email already registered (for registration)
​
401
error
Not authenticated - Missing or invalid Authorization header
​
401
error
Invalid token - Token not found in active tokens
​
401
error
Invalid credentials - Wrong email or password
​
502
error
Failed to connect to Zitadel (for SSO/token exchange)

Build docs developers (and LLMs) love

Get started for freeTalk to us