First Steps¶

Now that USSO is installed, let's walk through your first authentication flow.

1. Create Your First User¶

cURLPythonJavaScript

curl -X POST http://localhost:8000/api/sso/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]",
    "secret": "SecurePassword123!",
    "register": true
  }'

import requests

response = requests.post(
    "http://localhost:8000/api/sso/v1/auth/login",
    json={
        "identifier": "[email protected]",
        "secret": "SecurePassword123!",
        "register": true
    }
)

data = response.json()
print(f"User created: {data['user']['id']}")
print(f"Access token: {data['access_token']}")

const response = await fetch('http://localhost:8000/api/sso/v1/auth/login', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        identifier: '[email protected]',
        secret: 'SecurePassword123!',
        register: true
    })
});

const data = await response.json();
console.log('User created:', data.user.id);
console.log('Access token:', data.access_token);

2. Get User Information¶

Use the access token to get user details:

cURLPythonJavaScript

curl -X GET http://localhost:8000/api/sso/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {data['access_token']}"}
response = requests.get(
    "http://localhost:8000/api/sso/v1/me",
    headers=headers
)

user = response.json()
print(f"Logged in as: {user['identifiers'][0]['identifier']}")

const response = await fetch('http://localhost:8000/api/sso/v1/me', {
    headers: {
        'Authorization': `Bearer ${data.access_token}`
    }
});

const user = await response.json();
console.log('Logged in as:', user.identifiers[0].identifier);

3. Create a Workspace¶

Organize users into workspaces:

cURLPython

curl -X POST http://localhost:8000/api/sso/v1/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Team",
    "slug": "my-team"
  }'

response = requests.post(
    "http://localhost:8000/api/sso/v1/workspaces",
    headers=headers,
    json={
        "name": "My Team",
        "slug": "my-team"
    }
)

workspace = response.json()
print(f"Workspace created: {workspace['id']}")

4. Create a Role¶

Define permissions with roles:

cURLPython

curl -X POST http://localhost:8000/api/sso/v1/roles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editor",
    "slug": "editor",
    "scopes": ["read:posts", "write:posts"]
  }'

response = requests.post(
    "http://localhost:8000/api/sso/v1/roles",
    headers=headers,
    json={
        "name": "Editor",
        "slug": "editor",
        "scopes": ["read:posts", "write:posts"]
    }
)

role = response.json()
print(f"Role created: {role['slug']}")

5. Assign Role to User¶

Give users permissions:

cURLPython

curl -X PATCH http://localhost:8000/api/sso/v1/users/USER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["editor"]
  }'

response = requests.patch(
    f"http://localhost:8000/api/sso/v1/users/{user['id']}",
    headers=headers,
    json={"roles": ["editor"]}
)

print("Role assigned!")

6. Create a Service Account¶

For machine-to-machine authentication:

cURLPython

curl -X POST http://localhost:8000/api/sso/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Service",
    "scopes": ["read:users"]
  }'

response = requests.post(
    "http://localhost:8000/api/sso/v1/agents",
    headers=headers,
    json={
        "name": "API Service",
        "scopes": ["read:users"]
    }
)

agent = response.json()
print(f"Agent created: {agent['id']}")

7. Generate API Key¶

Create an API key for the service account:

cURLPython

curl -X POST http://localhost:8000/api/sso/v1/apikeys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "name": "Production Key"
  }'

response = requests.post(
    "http://localhost:8000/api/sso/v1/apikeys",
    headers=headers,
    json={
        "agent_id": agent['id'],
        "name": "Production Key"
    }
)

api_key = response.json()
print(f"API Key: {api_key['key']}")
# Save this key securely!

8. Integrate with Your App¶

Now integrate USSO with your application:

Python (FastAPI)¶

from fastapi import FastAPI, Depends
from usso.integrations.fastapi import get_authenticator
from usso.config import JWTConfig
from usso.schemas import UserData

# Configure USSO
config = JWTConfig(
    jwks_url="http://localhost:8000/.well-known/jwks.json",
    issuer="http://localhost:8000",
    audience="your-app"
)

authenticator = get_authenticator(config)
app = FastAPI()

@app.get("/protected")
def protected_route(user: UserData = Depends(authenticator)):
    return {
        "message": "Access granted",
        "user_id": user.sub,
        "roles": user.roles
    }

JavaScript (Express)¶

const express = require('express');
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const app = express();

const client = jwksClient({
    jwksUri: 'http://localhost:8000/.well-known/jwks.json'
});

function getKey(header, callback) {
    client.getSigningKey(header.kid, (err, key) => {
        const signingKey = key.publicKey || key.rsaPublicKey;
        callback(null, signingKey);
    });
}

async function verifyToken(req, res, next) {
    const token = req.headers.authorization?.split(' ')[1];

    if (!token) {
        return res.status(401).json({error: 'No token provided'});
    }

    jwt.verify(token, getKey, {
        audience: 'your-app',
        issuer: 'http://localhost:8000'
    }, (err, decoded) => {
        if (err) {
            return res.status(401).json({error: 'Invalid token'});
        }
        req.user = decoded;
        next();
    });
}

app.get('/protected', verifyToken, (req, res) => {
    res.json({
        message: 'Access granted',
        user_id: req.user.sub,
        roles: req.user.roles
    });
});

Next Steps¶

Now that you have the basics:

Core Concepts - Understand USSO's architecture
Authorization Guide - Learn about roles and scopes
Service Accounts - Deep dive into agents
Python SDK Guide - Complete SDK documentation

Common Tasks¶

Logout User¶

curl -X POST http://localhost:8000/api/sso/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Users¶

curl -X GET http://localhost:8000/api/sso/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Sessions¶

curl -X GET http://localhost:8000/api/sso/v1/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refresh Token¶

curl -X POST http://localhost:8000/api/sso/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

← Quick Start

Core Concepts →