Developer Documentation

Codevertex SSO API Reference & Integration Guide

Swagger UI

Interactive API documentation with try-it-out functionality

OpenAPI Spec

Download the OpenAPI 3.0 specification for code generation

Developer Portal

Create OAuth clients and manage API credentials

Quick Start

Base URL

Production APIbash
https://sso.codevertexitsolutions.com

Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

Authenticated Requestbash
curl -X GET "https://sso.codevertexitsolutions.com/api/v1/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example: User Login

Login Requestbash
curl -X POST "https://sso.codevertexitsolutions.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password",
    "tenant_slug": "your-tenant"
  }'

Response

Success Responsejson
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "roles": ["admin"],
    "permissions": ["auth.users.view", "auth.users.manage", "auth.tenants.view"]
  }
}

API Endpoints

Authentication

POST/api/v1/auth/register

Create a new user account

POST/api/v1/auth/login

Authenticate with email and password

POST/api/v1/auth/refresh

Refresh an expired access token

GET/api/v1/auth/me

Get current authenticated user

POST/api/v1/auth/logout

Invalidate the current session

POST/api/v1/auth/password-reset/request

Request password reset email

POST/api/v1/auth/password-reset/confirm

Confirm password reset with token

OAuth Providers

POST/api/v1/auth/oauth/google/start

Start Google OAuth flow

GET/api/v1/auth/oauth/google/callback

Handle Google OAuth callback

POST/api/v1/auth/oauth/github/start

Start GitHub OAuth flow

GET/api/v1/auth/oauth/github/callback

Handle GitHub OAuth callback

POST/api/v1/auth/oauth/microsoft/start

Start Microsoft OAuth flow

GET/api/v1/auth/oauth/microsoft/callback

Handle Microsoft OAuth callback

Multi-Factor Authentication

POST/api/v1/auth/mfa/totp/start

Start TOTP setup (returns QR code)

POST/api/v1/auth/mfa/totp/confirm

Confirm TOTP setup with code

POST/api/v1/auth/mfa/backup-codes/regenerate

Generate new backup codes

POST/api/v1/auth/mfa/backup-codes/consume

Use a backup code for authentication

OpenID Connect

GET/.well-known/openid-configuration

OIDC discovery document

GET/.well-known/jwks.json

JSON Web Key Set for token verification

GET/api/v1/authorize

OAuth2 authorization endpoint

POST/api/v1/token

OAuth2 token endpoint

GET/api/v1/userinfo

Get user info from access token

Admin & Tenant Management

Admin Scope Required
POST/api/v1/admin/tenants

Create a new tenant

GET/api/v1/admin/tenants

List all tenants

PUT/api/v1/admin/tenants/{id}

Update tenant details

DELETE/api/v1/admin/tenants/{id}

Delete a tenant workspace

POST/api/v1/admin/clients

Create an OAuth client

GET/api/v1/admin/clients

List OAuth clients

POST/api/v1/admin/entitlements

Manage service entitlements

POST/api/v1/admin/keys/rotate

Rotate signing keys

SDK Integration

JavaScript / TypeScript

Installation & Usagetypescript
// Example: TypeScript/Next.js with axios
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://sso.codevertexitsolutions.com/api/v1',
  withCredentials: true, // for httpOnly cookies
});

// Login endpoint
const response = await api.post('/auth/login', {
  email: 'user@example.com',
  password: 'password',
  tenant_slug: 'your-tenant',
});

const { access_token, user } = response.data;

// Use token in subsequent requests
api.defaults.headers.common['Authorization'] = `Bearer ${access_token}`;

// Get current user
const meResponse = await api.get('/auth/me');
console.log(meResponse.data.user);

Go

Installation & Usagego
// Install Shared Auth Client (JWT validation)
go get github.com/Bengo-Hub/shared-auth-client

// Use with Chi router middleware
import authclient "github.com/Bengo-Hub/shared-auth-client"

// Initialize JWT validator
validator := authclient.NewValidator(authclient.Config{
    IssuerURL: "https://sso.codevertexitsolutions.com",
    Audience:  "your-service",
})

// Add to router middleware
router.Use(authclient.AuthMiddleware(validator))

// Access claims in handlers
router.Get("/api/v1/protected", func(w http.ResponseWriter, r *http.Request) {
    claims := authclient.ClaimsFromContext(r.Context())
    userID := claims.Subject
    // ... handle request
})

SDK & Libraries

Auth API

Backend REST API for authentication, user management, and OAuth/OIDC flows.

View on GitHub

Service Client (Go)

Go SDK for inter-service communication, JWT validation, and middleware integration.

View on GitHub

Quick Installation

Go SDK Installationbash
go get github.com/Bengo-Hub/shared-service-client

Ready to integrate?

Create your OAuth client in the Developer Portal and start building with Codevertex SSO today.

Create OAuth ClientOpen Swagger UI