Insforge Client API
The Client API from Insforge — 35 operation(s) for client.
OpenAPI Specification
openapi: 3.0.3
info:
title: Insforge AI Admin Client API
version: 1.0.0
description: Model Gateway helper APIs for OpenRouter key provisioning, model discovery, and deprecated compatibility proxy routes
tags:
- name: Client
paths:
/api/ai/chat/completion:
post:
summary: Generate chat completion (deprecated)
deprecated: true
description: Deprecated compatibility proxy. New integrations should call https://openrouter.ai/api/v1/chat/completions directly with the provisioned OpenRouter key.
tags:
- Client
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatRequest'
responses:
'200':
description: Chat completion response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
text/event-stream:
schema:
type: string
description: Server-sent events stream for streaming responses
'400':
description: Invalid request - missing model or messages
'401':
description: Unauthorized
'500':
description: Failed to get response
/api/ai/image/generation:
post:
summary: Generate images (deprecated)
deprecated: true
description: Deprecated compatibility proxy. New integrations should use OpenRouter image-capable models directly with the provisioned OpenRouter key.
tags:
- Client
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationOptions'
responses:
'200':
description: Images generated successfully
content:
application/json:
schema:
type: object
properties:
model:
type: string
description: Model used for generation
images:
type: array
items:
$ref: '#/components/schemas/OpenRouterImageMessage'
text:
type: string
description: Text content from multimodal models
count:
type: integer
description: Number of images generated
metadata:
type: object
properties:
model:
type: string
revisedPrompt:
type: string
usage:
$ref: '#/components/schemas/TokenUsage'
nextActions:
type: string
example: Images have been generated successfully. Use the returned URLs or base64 data to access them.
'400':
description: Invalid request - missing model or prompt
'401':
description: Unauthorized
'500':
description: Failed to generate image
/api/ai/embeddings:
post:
summary: Generate embeddings (deprecated)
deprecated: true
description: Deprecated compatibility proxy. New integrations should call https://openrouter.ai/api/v1/embeddings directly with the provisioned OpenRouter key.
tags:
- Client
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingsRequest'
responses:
'200':
description: Embeddings generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingsResponse'
'400':
description: Invalid request - missing model or input
'401':
description: Unauthorized
'500':
description: Failed to generate embeddings
/api/auth/public-config:
get:
summary: Get public authentication configuration
description: Get all public authentication configuration including OAuth providers and email auth settings (public endpoint)
tags:
- Client
responses:
'200':
description: Public authentication configuration
content:
application/json:
schema:
type: object
properties:
oAuthProviders:
type: array
items:
type: string
enum:
- google
- github
- discord
- linkedin
- facebook
- instagram
- tiktok
- apple
- x
- spotify
- microsoft
customOAuthProviders:
type: array
items:
type: string
requireEmailVerification:
type: boolean
passwordMinLength:
type: integer
minimum: 4
maximum: 128
requireNumber:
type: boolean
requireLowercase:
type: boolean
requireUppercase:
type: boolean
requireSpecialChar:
type: boolean
verifyEmailMethod:
type: string
enum:
- code
- link
description: Method for email verification (code = 6-digit OTP, link = magic link)
resetPasswordMethod:
type: string
enum:
- code
- link
description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
disableSignup:
type: boolean
description: When true, new user sign-ups are disabled. Existing users can still sign in.
/api/auth/profiles/current:
patch:
summary: Update current user's profile
description: Update the profile of the currently authenticated user
tags:
- Client
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- profile
properties:
profile:
type: object
additionalProperties: true
description: Profile data (name, avatar_url, and any custom fields)
properties:
name:
type: string
avatar_url:
type: string
format: uri
responses:
'200':
description: Profile updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileResponse'
'400':
description: Invalid request
'401':
description: Unauthorized - authentication required
/api/auth/profiles/{userId}:
get:
summary: Get user profile by ID
description: Get public profile information for a user by their ID (public endpoint)
tags:
- Client
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
description: User ID
responses:
'200':
description: User profile
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileResponse'
'400':
description: Invalid user ID format
'404':
description: User not found
/api/auth/users:
post:
summary: Register new user
description: Creates a new user account
tags:
- Client
parameters:
- name: client_type
in: query
schema:
type: string
enum:
- web
- mobile
- desktop
- server
default: web
description: 'Client type determines how refresh tokens are returned:
- web: Refresh token stored in httpOnly cookie, csrfToken returned in response
- mobile/desktop/server: refreshToken returned directly in response body
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
example: user@example.com
password:
type: string
description: Password meeting configured requirements (check /api/auth/email/config for current requirements)
example: securepassword123
name:
type: string
example: John Doe
redirectTo:
type: string
format: uri
description: 'Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL. This URL must be included in allowedRedirectUrls. Recommended: use your app''s sign-in page.'
responses:
'200':
description: User created successfully
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/UserResponse'
accessToken:
type: string
nullable: true
description: JWT authentication token (null if email verification required)
csrfToken:
type: string
nullable: true
description: CSRF token for use with refresh endpoint (web clients only, null if email verification required)
refreshToken:
type: string
nullable: true
description: Refresh token for mobile/desktop/server clients (null for web clients or if email verification required)
requireEmailVerification:
type: boolean
description: Whether email verification is required before login
'400':
description: Invalid request
'403':
description: Signups disabled — project has disabled new user registration
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: AUTH_SIGNUP_DISABLED
message: User signups are disabled for this project.
statusCode: 403
'409':
description: User already exists
/api/auth/sessions:
post:
summary: User login
description: Authenticates user and returns access token. For web clients, sets httpOnly refresh token cookie. For mobile/desktop/server clients, returns refreshToken in response body.
tags:
- Client
parameters:
- name: client_type
in: query
schema:
type: string
enum:
- web
- mobile
- desktop
- server
default: web
description: 'Client type determines how refresh tokens are returned:
- web: Refresh token stored in httpOnly cookie, csrfToken returned in response
- mobile/desktop/server: refreshToken returned directly in response body
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
password:
type: string
responses:
'200':
description: Login successful
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/UserResponse'
accessToken:
type: string
csrfToken:
type: string
nullable: true
description: CSRF token for use with refresh endpoint (web clients only)
refreshToken:
type: string
nullable: true
description: Refresh token for mobile/desktop/server clients (null for web clients)
'401':
description: Invalid credentials
'403':
description: Email verification required
/api/auth/refresh:
post:
summary: Refresh access token
description: 'Refresh access token using refresh token.
- Web clients: Use httpOnly refresh token cookie with X-CSRF-Token header
- Mobile/Desktop/Server clients: Send refreshToken in request body
'
tags:
- Client
parameters:
- name: client_type
in: query
schema:
type: string
enum:
- web
- mobile
- desktop
- server
default: web
description: 'Client type determines how refresh tokens are handled:
- web: Refresh token from httpOnly cookie, requires X-CSRF-Token header
- mobile/desktop/server: refreshToken provided in request body, new refreshToken returned in response
'
- name: X-CSRF-Token
in: header
schema:
type: string
description: CSRF token received from login/register response (required for web clients only)
requestBody:
content:
application/json:
schema:
type: object
properties:
refreshToken:
type: string
description: Refresh token (required for mobile/desktop/server clients only)
responses:
'200':
description: Token refreshed successfully
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/UserResponse'
accessToken:
type: string
csrfToken:
type: string
nullable: true
description: New CSRF token for subsequent refresh requests (web clients only)
refreshToken:
type: string
nullable: true
description: New refresh token for mobile/desktop/server clients (must be persisted for next refresh)
'401':
description: No refresh token provided or user not found
'403':
description: Invalid CSRF token
/api/auth/logout:
post:
summary: Logout user
description: 'Logout the current client session.
Web clients use the httpOnly refresh token cookie. If a valid web refresh cookie is present,
the request must include the `X-CSRF-Token` header returned from login, registration, or refresh.
Missing, expired, invalid, or wrong-session-type refresh cookies are cleared idempotently and still
return success. Mobile, desktop, and server clients do not have server-side logout state and should
discard their stored refresh token after this request.
'
tags:
- Client
parameters:
- name: client_type
in: query
schema:
type: string
enum:
- web
- mobile
- desktop
- server
default: web
description: Client type. Web clients clear the httpOnly refresh cookie; other clients should discard their local refresh token.
- name: X-CSRF-Token
in: header
schema:
type: string
description: CSRF token required for web clients when a valid refresh cookie is present
responses:
'200':
description: Logged out successfully. Also returned when the refresh cookie is missing, expired, invalid, or the wrong session type.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
'403':
description: Invalid or missing CSRF token for a valid web refresh cookie
/api/auth/sessions/current:
get:
summary: Get current session
description: 'Returns the currently authenticated user''s basic info from the access token.
Project admin tokens return a projectAdmin session object instead of an auth.users row.
This endpoint does not refresh expired access tokens by itself.
For browser apps using the TypeScript SDK, call `auth.getCurrentUser()`
during startup. The SDK will use the httpOnly refresh cookie automatically
when it can refresh the session. Server, mobile, and other non-browser
clients should call `/api/auth/refresh` explicitly.
'
tags:
- Client
security:
- bearerAuth: []
responses:
'200':
description: Current session info
content:
application/json:
schema:
oneOf:
- type: object
required:
- user
additionalProperties: false
properties:
user:
$ref: '#/components/schemas/UserResponse'
- type: object
required:
- projectAdmin
additionalProperties: false
properties:
projectAdmin:
$ref: '#/components/schemas/ProjectAdminResponse'
'401':
description: Unauthorized
/api/auth/email/send-verification:
post:
summary: Send email verification (code or link based on config)
description: Send email verification using the method configured in auth settings (verifyEmailMethod). When method is 'code', sends a 6-digit numeric code. When method is 'link', sends a browser verification link that goes through an InsForge backend endpoint first. Prevents user enumeration by returning success even if email doesn't exist.
tags:
- Client
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
example: user@example.com
redirectTo:
type: string
format: uri
description: 'Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL. This URL must be included in allowedRedirectUrls. Recommended: use your app''s sign-in page.'
responses:
'202':
description: Verification email sent (if email exists). Message varies based on configured method.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: If your email is registered, we have sent you a verification code/link. Please check your inbox.
'400':
description: Invalid request
/api/auth/email/verify-link:
get:
summary: Verify email from browser link click
description: 'Browser-oriented link verification flow.
This endpoint is intended for users clicking verification links in email.
It validates the token on the backend and redirects the browser to the
stored, validated `redirectTo` URL with the verification result.
Redirect query params:
- Success: `insforge_status=success&insforge_type=verify_email`
- Error: `insforge_status=error&insforge_type=verify_email&insforge_error=...`
- `insforge_status`: `success` or `error`
- `insforge_type`: always `verify_email`
- `insforge_error`: present only on error, human-readable message
Recommended handling: use your sign-in page as `redirectTo`. When the
redirect arrives with `insforge_status=success`, show a confirmation message
and ask the user to sign in with their email and password.
'
tags:
- Client
parameters:
- name: token
in: query
required: true
schema:
type: string
description: 64-character email verification token from the email link
responses:
'302':
description: Browser redirected to the stored redirect URL
'400':
description: Invalid verification token or redirect target
/api/auth/email/verify:
post:
summary: Verify email with code
description: 'Verify email address with a 6-digit code.
Successfully verified users will receive a session token.
Browser email clicks should use `GET /api/auth/email/verify-link`.
`POST /api/auth/email/verify` is the JSON API for 6-digit code submission.
'
tags:
- Client
parameters:
- name: client_type
in: query
schema:
type: string
enum:
- web
- mobile
- desktop
- server
default: web
description: 'Client type determines how refresh tokens are returned:
- web: Refresh token stored in httpOnly cookie, csrfToken returned in response
- mobile/desktop/server: refreshToken returned directly in response body
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- otp
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
otp:
type: string
pattern: ^\d{6}$
description: 6-digit verification code
example: '123456'
responses:
'200':
description: Email verified successfully, session created
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/UserResponse'
accessToken:
type: string
description: JWT authentication token
csrfToken:
type: string
nullable: true
description: CSRF token for use with refresh endpoint (web clients only)
refreshToken:
type: string
nullable: true
description: Refresh token for mobile/desktop/server clients (null for web clients)
'400':
description: Invalid verification code or token
'401':
description: Verification code/token expired or invalid
/api/auth/email/send-reset-password:
post:
summary: Send password reset (code or link based on config)
description: Send password reset email using the method configured in auth settings (resetPasswordMethod). When method is 'code', sends a 6-digit numeric code for two-step flow. When method is 'link', sends a browser reset link that goes through an InsForge backend endpoint first. Prevents user enumeration by returning success even if email doesn't exist.
tags:
- Client
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
example: user@example.com
redirectTo:
type: string
format: uri
description: 'Used for link-based password reset. The email link always opens an InsForge backend endpoint first; InsForge then redirects the browser to this URL with the reset token in the query string. This URL must be included in allowedRedirectUrls. Recommended: use your app''s dedicated reset-password page.'
responses:
'202':
description: Password reset email sent (if email exists). Message varies based on configured method.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: If your email is registered, we have sent you a password reset code/link. Please check your inbox.
'400':
description: Invalid request
/api/auth/email/exchange-reset-password-token:
post:
summary: Exchange reset password code for reset token
description: 'Step 1 of two-step password reset flow (only used when resetPasswordMethod is ''code''):
1. Verify the 6-digit code sent to user''s email
2. Return a reset token that can be used to actually reset the password
This endpoint is not used when resetPasswordMethod is ''link'', because the browser reset-link flow uses the emailed link token directly.
'
tags:
- Client
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- code
properties:
email:
type: string
format: email
example: user@example.com
code:
type: string
pattern: ^\d{6}$
description: 6-digit numeric code from email
example: '123456'
responses:
'200':
description: Code verified successfully, reset token returned
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Reset token to be used in reset-password endpoint
expiresAt:
type: string
format: date-time
description: Token expiration timestamp
'400':
description: Invalid request
'401':
description: Invalid or expired code
/api/auth/email/reset-password-link:
get:
summary: Open password reset flow from browser link click
description: 'Browser-oriented password reset link flow.
This endpoint is intended for users clicking password reset links in email.
It validates the token on the backend and redirects the browser to the
stored, validated `redirectTo` URL with the reset token in the query string.
Redirect query params:
- Ready: `token=...&insforge_status=ready&insforge_type=reset_password`
- Error: `insforge_status=error&insforge_type=reset_password&insforge_error=...`
- `token`: present only when `insforge_status=ready`
- `insforge_status`: `ready` or `error`
- `insforge_type`: always `reset_password`
- `insforge_error`: present only on error, human-readable message
Your app should render the reset-password form only when `insforge_status=ready`
and `token` is present.
'
tags:
- Client
parameters:
- name: token
in: query
required: true
schema:
type: string
description: 64-character password reset token from the email link
responses:
'302':
description: Browser redirected to the stored redirect URL
'400':
description: Invalid reset token or redirect target
/api/auth/email/reset-password:
post:
summary: Reset password with token
description: 'Reset user password with a token. The token can be:
- Magic link token (64-character hex token from send-reset-password when method is ''link'')
- Reset token (from exchange-reset-password-token after code verification when method is ''code'')
Both token types use RESET_PASSWORD purpose and are verified the same way.
Flow summary:
- Code method: send-reset-password → exchange-reset-password-token → reset-password (with resetToken)
- Link method: send-reset-password → GET /api/auth/email/reset-password-link → reset-password
'
tags:
- Client
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- newPassword
- otp
properties:
newPassword:
type: string
description: New password meeting configured requirements
example: newSecurePassword123
otp:
type: string
description: Reset token (either from magic link or from exchange-reset-password-token endpoint)
example: a1b2c3d4...
responses:
'200':
description: Password reset successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Password reset successfully
'400':
description: Invalid request or password requirements not met
'401':
description: Verification code/token expired or invalid
/api/auth/oauth/{provider}:
get:
summary: Initiate OAuth flow (PKCE)
description: 'Generate OAuth authorization URL for any supported provider using PKCE flow.
For mobile/desktop/server clients using PKCE:
1. Generate code_verifier (random string, 43-128 chars)
2. Generate code_challenge = Base64URL(SHA256(code_verifier))
3. Call this endpoint with code_challenge
4. After OAuth callback, use /api/auth/oauth/exchange with code_verifier
'
tags:
- Client
parameters:
- name: provider
in: path
required: true
schema:
type: string
enum:
- google
- github
- discord
- linkedin
- facebook
- instagram
- tiktok
- apple
- x
- spotify
- microsoft
- name: redirect_uri
in: query
required: true
schema:
type: string
format: uri
description: URL to redirect after authentication (receives insforge_code parameter)
- name: code_challenge
in: query
required: false
schema:
type: string
descrip
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insforge/refs/heads/main/openapi/insforge-client-api-openapi.yml