API Tokens

ModelWorks uses JSON Web Tokens (JWT) to authenticate and authorize requests against your circuits. These tokens grant your applications secure access to query public or protected circuits.

Generating Tokens

1. Navigate to Settings → API Tokens in your user dashboard.
2. Click Add Token to launch the token-creation dialog.
3. Choose a descriptive name and scope, then confirm to mint a new token.
4. Copy the token immediately—this is the only time you can view the full value.

Managing Tokens

• Revoke: Click the delete (🗑) icon next to a token to immediately revoke its access.
• Pagination: If you have many tokens, use the pagination controls at the bottom to browse.
• Session Highlight: Your current session’s token is marked to help you avoid accidental revocation.

Using Tokens in API Requests

Include your token in the HTTP Authorization header using the Bearer scheme:

POST /circuits/query HTTP/1.1
Host: api.modelworks.ai
Authorization: Bearer YOUR_TOKEN_VALUE_HERE
Content-Type: application/json

{
  "context": { "version": "<VERSION_UID>" },
  "input": { /* your inputs */ }
}

Note: Always prefix the token with Bearer and keep it confidential.

Best Practices & Security

• Limit Scope: Create separate tokens for different applications or services.
• Rotate Regularly: Periodically revoke and regenerate tokens to reduce risk.
• Secure Storage: Store tokens in environment variables or secret management tools, never in code.
• Least Privilege: Only grant tokens the minimum permissions needed—read-only tokens for querying public circuits, higher privileges for protected or private circuits.

Limitations

• Tokens are strictly for authenticating API calls—they cannot be used within circuit definitions, inputs, or outputs.
• Secrets and tokens are stored encrypted at rest and are only accessible via secure endpoints.