Quickstart Guide

Get your first AuthSec authentication flow running in under 10 minutes.

Prerequisites

• API access to AuthSec instance
• A tenant ID (contact your administrator)
• Tool for making HTTP requests (curl, Postman, or similar)

Step 1: Create an Admin User

First, create an admin user in your tenant.

Endpoint: POST /uflow/admin/users

curl -X POST https://dev.api.authsec.dev/uflow/admin/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "username": "[email protected]",
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "first_name": "John",
    "last_name": "Doe",
    "tenant_id": "your-tenant-id"
  }'

Response:

{
  "id": "user-123-abc",
  "username": "[email protected]",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "tenant_id": "your-tenant-id",
  "active": true,
  "created_at": "2026-02-11T19:56:00Z"
}

Step 2: Authenticate the User

Authenticate using the created credentials to obtain a JWT token.

Endpoint: POST /uflow/admin/auth/login

curl -X POST https://dev.api.authsec.dev/uflow/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user-123-abc",
    "username": "[email protected]",
    "email": "[email protected]"
  }
}

Step 3: Use the Access Token

Use the access token to make authenticated requests.

Endpoint: GET /uflow/admin/users/me

curl -X GET https://dev.api.authsec.dev/uflow/admin/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "id": "user-123-abc",
  "username": "[email protected]",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "tenant_id": "your-tenant-id",
  "active": true,
  "roles": ["admin"],
  "permissions": ["users:read", "users:write"]
}

Authentication Flow Diagram

sequenceDiagram
    participant Client
    participant UserFlow
    participant AuthManager
    
    Client->>UserFlow: POST /admin/auth/login<br/>{username, password}
    UserFlow->>UserFlow: Validate credentials
    UserFlow->>AuthManager: Request JWT token
    AuthManager->>UserFlow: Return token
    UserFlow->>Client: Return access_token
    
    Client->>UserFlow: GET /admin/users/me<br/>Authorization: Bearer token
    UserFlow->>AuthManager: Validate token
    AuthManager->>UserFlow: Token valid
    UserFlow->>Client: Return user profile

Complete Example (Python)

import requests

# Configuration
BASE_URL = "https://dev.api.authsec.dev"
TENANT_ID = "your-tenant-id"

# Step 1: Login
login_response = requests.post(
    f"{BASE_URL}/uflow/admin/auth/login",
    json={
        "username": "[email protected]",
        "password": "SecurePassword123!"
    }
)
login_data = login_response.json()
access_token = login_data["access_token"]

print(f"✓ Authenticated successfully")
print(f"Token: {access_token[:50]}...")

# Step 2: Get user profile
profile_response = requests.get(
    f"{BASE_URL}/uflow/admin/users/me",
    headers={"Authorization": f"Bearer {access_token}"}
)
profile = profile_response.json()

print(f"✓ Retrieved profile for: {profile['username']}")
print(f"Roles: {', '.join(profile['roles'])}")

# Step 3: List all users (if authorized)
users_response = requests.get(
    f"{BASE_URL}/uflow/admin/users",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"tenant_id": TENANT_ID}
)
users = users_response.json()

print(f"✓ Found {len(users['items'])} users in tenant")

Complete Example (TypeScript)

// Configuration
const BASE_URL = "https://dev.api.authsec.dev";
const TENANT_ID = "your-tenant-id";

interface LoginResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
}

interface UserProfile {
  id: string;
  username: string;
  email: string;
  roles: string[];
  permissions: string[];
}

async function quickstart() {
  // Step 1: Login
  const loginResponse = await fetch(`${BASE_URL}/uflow/admin/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: '[email protected]',
      password: 'SecurePassword123!'
    })
  });
  
  const loginData: LoginResponse = await loginResponse.json();
  const accessToken = loginData.access_token;
  
  console.log('✓ Authenticated successfully');
  console.log(`Token: ${accessToken.substring(0, 50)}...`);
  
  // Step 2: Get user profile
  const profileResponse = await fetch(`${BASE_URL}/uflow/admin/users/me`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  
  const profile: UserProfile = await profileResponse.json();
  
  console.log(`✓ Retrieved profile for: ${profile.username}`);
  console.log(`Roles: ${profile.roles.join(', ')}`);
  
  // Step 3: List all users
  const usersResponse = await fetch(
    `${BASE_URL}/uflow/admin/users?tenant_id=${TENANT_ID}`,
    { headers: { 'Authorization': `Bearer ${accessToken}` }}
  );
  
  const users = await usersResponse.json();
  console.log(`✓ Found ${users.items.length} users in tenant`);
}

quickstart();

Common Issues

Issue: "Unauthorized" (401)

Cause: Invalid or expired token

Solution:

• Check token is included in Authorization: Bearer TOKEN header
• Verify token hasn't expired (default: 1 hour)
• Re-authenticate to get a new token

Issue: "Forbidden" (403)

Cause: User lacks required permissions

Solution:

• Verify user has appropriate roles/permissions
• Check tenant_id matches the resource being accessed
• Review RBAC configuration

Issue: "Not Found" (404)

Cause: Incorrect endpoint or resource doesn't exist

Solution:

• Verify base URL is correct
• Check endpoint path matches documentation
• Confirm resource ID exists

Next Steps

Now that you have basic authentication working:

1. Add MFA - Enhance security with multi-factor authentication
2. Create Roles - Set up role-based access control
3. Manage Users - Learn advanced user management
4. Explore Authentication Flows - Understand all available authentication methods

Sample Projects

[!TIP] Check out complete sample applications in our SDK repositories:

• Python SDK: /sdk/examples/quickstart.py
• TypeScript SDK: /sdk/ts/examples/quickstart.ts

---

Questions? Continue to Authentication Flows to learn about other authentication methods →