Connected Apps

App: "I need to list your agents"
  │
  └─ Sends request with access token
     curl -H "Authorization: Bearer eyJ..." \
     https://api.noorle.com/agents
     │
     └─ Noorle verifies token
     └─ Allows access (user approved)
     └─ Returns: Your agents

Console → Settings → Connected Apps
├─ MyApp (connected 3/22)
│  ├─ Permissions: read, execute
│  ├─ Last used: Today 2:30 PM
│  └─ [Revoke]
│
└─ All tokens immediately invalid
   App can't access anymore

User clicks "Connect Noorle"
  │
  └─ App registers dynamically
     ├─ Sends app details to Noorle
     ├─ Noorle generates client_id, client_secret
     ├─ User authorizes
     └─ App gets access token

Console → Developer → OAuth Apps
├─ Create App
│  ├─ App name: "MyAnalytics"
│  ├─ Description: "Analytics integration"
│  ├─ Redirect URI: https://myapp.example.com/callback
│  ├─ Logo URL: https://myapp.example.com/logo.png
│  │
│  └─ Generated credentials:
│     ├─ client_id: "app_abc123xyz"
│     └─ client_secret: "secret_def456uvw"
│        (save securely, don't share)

Available scopes:
├─ read         (list, view resources)
├─ execute      (run agents, call tools)
├─ manage       (create, update resources)
├─ admin        (full control, delete)
└─ offline_access (get refresh token)

Scopes: read offline_access

Why:
├─ read = can view agents, memory, results
├─ NOT execute = can't run agents (just read data)
├─ offline_access = refresh token for background jobs

Scopes: read execute manage offline_access

Why:
├─ read = view agents
├─ execute = run agents for user
├─ manage = let user create agents
├─ offline_access = refresh token for 24/7 monitoring

https://auth.noorle.com/oauth/authorize?
  client_id=app_abc123xyz
  &scope=read%20execute%20offline_access
  &redirect_uri=https://app.example.com/callback
  &state=random-string-to-prevent-csrf
  &response_type=code

https://app.example.com/callback?
  code=AUTH_CODE_123
  &state=random-string-to-prevent-csrf

// Verify state matches (prevents CSRF)
if (request.state !== session.state) {
  throw new Error("State mismatch - possible CSRF");
}

// Exchange code for token

POST https://api.noorle.com/oauth/token

Body:
{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_123",
  "client_id": "app_abc123xyz",
  "client_secret": "secret_def456uvw"  // backend only!
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

curl -H "Authorization: Bearer eyJhbGc..." \
     https://api.noorle.com/agents

Response:
{
  "agents": [
    { "id": "...", "name": "ResearchBot" },
    { "id": "...", "name": "SupportBot" }
  ]
}

Console → Settings → Connected Apps
├─ App1
│  ├─ Status: Active
│  ├─ Scopes: read execute
│  ├─ Connected: March 22, 2024
│  ├─ Last used: March 22, 2:30 PM
│  └─ Actions: [Revoke]
│
├─ App2
│  ├─ Status: Active
│  ├─ Scopes: read offline_access
│  ├─ Connected: February 15, 2024
│  ├─ Last used: Never
│  └─ Actions: [Revoke]
│
└─ App3
   ├─ Status: Inactive (pending confirmation)
   └─ Actions: [Approve] [Deny]

# Via Console (instant)
Console → Settings → Connected Apps → [App Name] → [Revoke]

# Via API
DELETE /api/account/oauth-clients/{client_id}/authorization

Access token expires (1 hour)
  │
  └─ App uses refresh token to get new access token
     │
     └─ No user interaction needed
        App continues working in background

1. User connects app (scope: offline_access)
2. User goes away
3. 11 PM: App wakes up, needs to run report
4. App's access token expired
5. App refreshes using refresh token
6. Generates report (automatic)
7. User wakes up to report in inbox

// INSECURE: HTTP redirect
const redirectUri = "http://app.example.com/callback";
// Token could be intercepted

// SECURE: HTTPS redirect
const redirectUri = "https://app.example.com/callback";
// TLS encryption protects token

// BAD: Client secret in browser
const clientSecret = "secret_def456uvw";
// Anyone can view in network tab

// GOOD: Client secret on backend
// Stored in .env file, Docker secret, etc.
// Never sent to browser

Mobile App
  │
  ├─ Generate random string (code_verifier)
  │
  ├─ Send to Noorle
  │  + code_challenge (hash of code_verifier)
  │
  ├─ Receive authorization code
  │
  └─ Exchange code for token
     + code_verifier (proves app = same as before)
        (Attacker can't intercept and use code)

{
  "app_name": "Analytics Dashboard",
  "scopes": ["read", "offline_access"],
  "flow": "User authorizes once. App periodically fetches agent metrics."
}

{
  "app_name": "Slack to Noorle",
  "scopes": ["read", "execute", "manage", "offline_access"],
  "flow": "User authorizes. Slack app creates agents, executes them, reports back."
}