Authentication

Overview

AWorld uses AWS Cognito with a custom domain for authentication, implementing standard OAuth2 flows. The platform supports both user-centric authentication and machine-to-machine (M2M) authorization through client credentials.

Authentication Methods

User Authentication (OAuth2)

For user-centric applications, AWorld implements the standard OAuth2 authorization code flow:

Authorization Request: The client redirects the user to the Cognito authorization endpoint

User Authentication: The user authenticates with their credentials

Authorization Code: Upon successful authentication, the authorization server redirects back with an authorization code

Token Exchange: The client exchanges the authorization code for access and refresh tokens

API Access: The client uses the access token to make authenticated API requests

Machine-to-Machine Authentication (Client Credentials)

For M2M interactions, AWorld supports the OAuth2 client credentials flow:

Token Request: The client makes a direct request to the token endpoint with client ID and secret

Token Response: The authorization server returns access tokens

API Access: The client uses the access token to make authenticated API requests

Token Types

Access Token

Used to access protected resources and APIs

JWT format containing claims about the authenticated user or client

Short-lived (typically 1 hour)

Must be included in API requests as a Bearer token in the Authorization header

Refresh Token

Used to obtain new access tokens when they expire

Long-lived (typically 30 days)

Should be securely stored by the client

Cannot be used to access protected resources directly

ID Token

Contains user identity information

JWT format

Used by the client application to verify the user's identity

Not intended for API authorization

Authentication Endpoints

Endpoint	Description
`https://auth.aworld.cloud/oauth2/authorize`	Authorization endpoint for initiating OAuth2 flows
`https://auth.aworld.cloud/oauth2/token`	Token endpoint for obtaining access tokens
`https://auth.aworld.cloud/oauth2/userInfo`	User info endpoint for obtaining user details

User Contexts and Access Levels

Principal (Platform-level User)

Principals have access across accounts and typically represent administrators or super-users.

User (Workspace-level User)

Users are scoped to a specific workspace within an account, with permissions limited to their assigned workspace.

Integrating with AWorld Authentication

Web Applications

For web applications, we recommend using the authorization code flow with PKCE (Proof Key for Code Exchange):

Mobile Applications

Mobile applications should also use the authorization code flow with PKCE, typically using a system browser or in-app browser tab.

Server-side Applications

Server-side applications can use the client credentials flow to obtain access tokens without user interaction:

Note: The correct token endpoint for AWorld is https://auth.aworld.cloud/oauth2/token

Best Practices

Never expose client secrets in public-facing applications (use authorization code flow with PKCE instead)

Always validate tokens before trusting their content

Store refresh tokens securely to prevent unauthorized access

Implement token renewal to handle token expiration

Use HTTPS for all authentication-related requests

Implement proper error handling for authentication failures

Limit scope requests to only what your application needs

Implement proper logout to clean up sessions and tokens

Common Issues and Troubleshooting

Invalid Token

If you receive an "Invalid token" error, the token may have expired or been tampered with. Request a new access token using your refresh token.

Invalid Grant

This typically occurs when trying to use an authorization code more than once or when using an expired refresh token.

Unauthorized Client

This error indicates that the client doesn't have permission to use the requested grant type or scopes.

Additional Resources

OAuth 2.0 Specification

AWS Cognito Documentation

JWT.io - For debugging JSON Web Tokens

Overview#

Authentication Methods#

User Authentication (OAuth2)#

Machine-to-Machine Authentication (Client Credentials)#

Token Types#

Access Token#

Refresh Token#

ID Token#

Authentication Endpoints#

User Contexts and Access Levels#

Principal (Platform-level User)#

User (Workspace-level User)#

Integrating with AWorld Authentication#

Web Applications#

Mobile Applications#

Server-side Applications#

Best Practices#

Common Issues and Troubleshooting#

Invalid Token#

Invalid Grant#

Unauthorized Client#

Additional Resources#