Authentication Settings

You can secure your agent endpoints using two authentication options:

• Bearer Token — simple API key passed in the request header
• OAuth OIDC — connect to an identity provider and enforce user-level access

Use a Bearer Token

This method lets you authenticate API calls with a shared secret. It’s suitable for internal tools and programmatic access.

Getting Started

1. Generate a secure token string (you can use any random value).
2. Go to your agent’s Settings.
3. Scroll to Authentication and paste your token.
4. When calling the agent, pass the token in your request headers.

Example

curl https://your-agent.smythos.com/api/v1/chat \
  -H "Authorization: Bearer abc123xyz789"

No third-party setup needed

Bearer Token is ideal for testing and backend automations without needing an identity provider.

Use OAuth OIDC

Use OAuth with OpenID Connect (OIDC) when you need fine-grained user authentication, such as SSO or domain-based restrictions.

This lets you delegate identity to providers like Google, Microsoft, Auth0, or your own OIDC-compatible service.

What you’ll configure

Field	Description	Example
OIDC Config Endpoint	Discovery URL from provider	https://example.com/.well-known/openid-configuration
Client ID	Your app’s public ID	abc123clientid
Client Secret	Confidential app credential	xyz789clientsecret
Allowed Emails	Who can access the agent	["user@example.com", "*.org"]
Callback URL	Redirect URL after login	https://youragent.smythos.com/chatbot/callback

You’ll enter this info under the Authentication section in Agent Settings.

Build Your Callback URL

SmythOS constructs your callback URL from your agent’s subdomain.

Format

https://{your-subdomain}.smythos.com/chatbot/callback

Replace {your-subdomain} with your actual agent name.

Example

https://myagent.smythos.com/chatbot/callback

Callback URL must match exactly

Your OAuth provider will reject mismatches. Double-check spacing, casing, and characters.

Restrict Access by Email

Use Allowed Emails to restrict agent access to specific users or domains.

Individual user: user@example.com
Entire domain: @example.org
Use wildcard: *.example.com

This means only those users can pass the OAuth login flow.

Behind the Scenes

When you provide the OIDC Config Endpoint, SmythOS fetches this JSON automatically:

{
  "authorization_endpoint": "https://example.com/auth",
  "token_endpoint": "https://example.com/token",
  "userinfo_endpoint": "https://example.com/userinfo",
  "jwks_uri": "https://example.com/.well-known/jwks.json"
}

You don’t need to configure each endpoint manually.

Where This Connects in SmythOS

• View or change auth settings in Manage Agents
• Link to secure Chat Interfaces
• Use with Deployed Endpoints
• Monitor auth errors in the Logs Explorer

Troubleshooting Auth Issues

Problem	What to check
Login fails	Double-check OIDC client ID, secret, or discovery URL
Unauthorized error	Verify Bearer token matches
Callback error	Must use HTTPS and match exactly
Access denied	Email may not be in allowed list
Request blocked	Review CORS and redirect URIs in provider config

Need to debug?

Check the Logs tab in your agent’s settings for auth errors. Go to Debugging for a full walkthrough.