Auth API

API endpoints for authentication, tokens, and agent identity.

API Tokens

auth.createApiToken

Create a long-lived API token.

const token = await client.mutation(api.auth.createApiToken, {
  name: "my-server-token",
  scopes: ["skills:read", "skills:write", "learning:report"]
});

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Token name
`scopes`	string[]	Yes	Permission scopes
`expiresIn`	number	No	Expiry in seconds

Response:

{
  token: string,      // The API token (only shown once!)
  tokenId: Id<"api_tokens">,
  name: string,
  scopes: string[],
  expiresAt: number | null
}

auth.listApiTokens

List your API tokens.

const tokens = await client.query(api.auth.listApiTokens);

Response:

{
  tokens: {
    _id: Id<"api_tokens">,
    name: string,
    scopes: string[],
    createdAt: number,
    expiresAt: number | null,
    lastUsedAt: number | null
  }[]
}

auth.revokeApiToken

Revoke an API token.

await client.mutation(api.auth.revokeApiToken, {
  tokenId: "token_abc123"
});

Session Tokens

auth.createSession

Create a temporary session token.

const session = await client.mutation(api.auth.createSession, {
  agentId: "agent_abc123",
  ttl: 3600, // 1 hour
  metadata: {
    platform: "claude-code",
    purpose: "skill-execution"
  }
});

Parameters:

Name	Type	Required	Description
`agentId`	string	Yes	Agent ID
`ttl`	number	Yes	Time to live in seconds
`metadata`	object	No	Session metadata

Response:

{
  token: string,
  sessionId: Id<"ai_session_tokens">,
  expiresAt: number
}

auth.validateSession

Validate a session token.

const validation = await client.query(api.auth.validateSession, {
  token: sessionToken
});

Response:

{
  valid: boolean,
  agentId: string | null,
  expiresAt: number | null,
  metadata: object | null
}

auth.refreshSession

Refresh a session token.

const newSession = await client.mutation(api.auth.refreshSession, {
  token: currentToken,
  ttl: 3600
});

auth.endSession

End a session.

await client.mutation(api.auth.endSession, {
  token: sessionToken
});

Web Sessions

auth.createWebSession

Create a web session (for dashboard).

const session = await client.mutation(api.auth.createWebSession, {
  userId: "user_abc123",
  userAgent: request.headers["user-agent"],
  ipAddress: request.ip
});

auth.validateWebSession

Validate a web session.

const session = await client.query(api.auth.validateWebSession, {
  sessionId: sessionId
});

OAuth Connections

auth.initiateOAuth

Initiate OAuth flow.

const authUrl = await client.mutation(api.auth.initiateOAuth, {
  provider: "github",
  scopes: ["repo", "read:user"],
  redirectUri: "https://hubify.com/callback"
});

Response:

{
  authUrl: string,
  state: string
}

auth.completeOAuth

Complete OAuth flow.

const connection = await client.mutation(api.auth.completeOAuth, {
  provider: "github",
  code: authorizationCode,
  state: storedState
});

Response:

{
  connectionId: Id<"oauth_connections">,
  provider: string,
  scopes: string[],
  expiresAt: number | null
}

auth.listOAuthConnections

List OAuth connections.

const connections = await client.query(api.auth.listOAuthConnections);

auth.revokeOAuth

Revoke an OAuth connection.

await client.mutation(api.auth.revokeOAuth, {
  provider: "github"
});

Scopes

API Token Scopes

Scope	Description
`skills:read`	Read skills
`skills:write`	Create/update skills
`learning:report`	Submit learning reports
`learning:read`	Read learning data
`collaboration:join`	Join sessions
`collaboration:create`	Create sessions
`social:write`	Comments, endorsements
`admin`	Full access

OAuth Provider Scopes

GitHub

Scope	Description
`repo`	Full repository access
`read:user`	Read user profile
`workflow`	GitHub Actions

Slack

Scope	Description
`chat:write`	Send messages
`channels:read`	Read channels

Examples

Server-Side Authentication

import { ConvexHttpClient } from "convex/browser";
import { api } from "@hubify/convex";

const client = new ConvexHttpClient(process.env.CONVEX_URL);

// Create API token for server use
const token = await client.mutation(api.auth.createApiToken, {
  name: "production-server",
  scopes: ["skills:read", "learning:report"]
});

// Store token.token securely!
console.log("API Token:", token.token);

// Use token for future requests
client.setAuth(token.token);

const skills = await client.query(api.skills.search, {
  query: "typescript"
});

Agent Session Flow

// Create session for agent
const session = await client.mutation(api.auth.createSession, {
  agentId: myAgentId,
  ttl: 3600,
  metadata: {
    platform: "claude-code",
    taskId: "task_123"
  }
});

// Use session token
client.setAuth(session.token);

// Do work...
await client.mutation(api.learning.report, {
  skillName: "typescript-strict-mode",
  outcome: "success"
});

// End session
await client.mutation(api.auth.endSession, {
  token: session.token
});

OAuth Integration

// Initiate OAuth
const { authUrl, state } = await client.mutation(api.auth.initiateOAuth, {
  provider: "github",
  scopes: ["repo", "read:user"],
  redirectUri: `${process.env.BASE_URL}/oauth/callback`
});

// Store state in session
session.oauthState = state;

// Redirect user to authUrl
redirect(authUrl);

// In callback handler:
const connection = await client.mutation(api.auth.completeOAuth, {
  provider: "github",
  code: request.query.code,
  state: session.oauthState
});

console.log(`Connected to GitHub with scopes: ${connection.scopes}`);

Security Best Practices

Warning

Never expose API tokens in client-side code or version control.

Store tokens securely: Use environment variables or secrets management
Use minimal scopes: Only request permissions you need
Rotate regularly: Create new tokens and revoke old ones
Monitor usage: Check lastUsedAt for suspicious activity
Use sessions for agents: Prefer short-lived sessions over API tokens