WeTrials Developers

Appearance

OAuth 2.0 Overview ​

Introduction ​

WeTrials OAuth 2.0 service provides secure authorization for third-party applications to access WeTrials user data and resources. Our implementation follows the OAuth 2.0 specification (RFC 6749) with additional security measures including PKCE (Proof Key for Code Exchange) support.

Why Use OAuth 2.0? ​

OAuth 2.0 enables:

  • Secure Authorization: Users can grant limited access to their data without sharing passwords
  • Granular Permissions: Applications request specific scopes for targeted access
  • Token-Based Authentication: Short-lived access tokens and refresh tokens for secure API access
  • User Control: Users can revoke access at any time

Supported OAuth Flows ​

The Authorization Code flow with PKCE is the most secure and recommended approach for all applications, including:

  • Server-side web applications
  • Single-page applications (SPAs)
  • Mobile applications
  • Desktop applications

Key Features:

  • Most secure OAuth flow
  • PKCE protection against code interception attacks
  • Refresh token support for long-lived access
  • Suitable for public and confidential clients

Key Concepts ​

Client Application ​

Your application that requests access to WeTrials user data. Each application must be registered to obtain:

  • Client ID: Public identifier for your application
  • Client Secret: Confidential key for server-side applications (not used with PKCE for public clients)
  • Redirect URIs: Authorized callback URLs for your application

Access Token ​

A short-lived token (typically 1 hour) that grants access to WeTrials APIs. Access tokens are:

  • JWT (JSON Web Token) format
  • Include granted scopes and user information
  • Must be included in API request headers

Refresh Token ​

A long-lived token (30 days by default) used to obtain new access tokens without user interaction. Refresh tokens:

  • Should be stored securely
  • Can be revoked by users or administrators
  • Are rotated on each use for enhanced security

Scopes ​

Permissions that define what resources and operations your application can access. Examples:

  • read:profile - Read user profile information
  • write:studies - Create and modify studies
  • read:participants - Access participant data

Authorization Endpoint ​

https://auth.wetrials.com/v1/oauth/authorize

Where users are redirected to grant permissions to your application.

Token Endpoint ​

https://auth.wetrials.com/v1/oauth/token

Where your application exchanges authorization codes for access tokens.

OAuth Flow Overview ​

mermaid
sequenceDiagram
    participant User
    participant App as Your Application
    participant Auth as WeTrials Auth
    participant API as WeTrials API

    User->>App: Initiates login
    App->>Auth: Redirect to /authorize
    Auth->>User: Show login & consent
    User->>Auth: Approve access
    Auth->>App: Redirect with auth code
    App->>Auth: Exchange code for tokens
    Auth->>App: Return access & refresh tokens
    App->>API: API request with access token
    API->>App: Return protected data

Getting Started ​

1. Register Your Application ​

Contact the WeTrials team to register your OAuth application and receive your client credentials.

2. Choose Your Implementation ​

  • Server-side applications: Use Authorization Code flow with client secret
  • SPAs and mobile apps: Use Authorization Code flow with PKCE
  • Machine-to-machine: Contact us for service account setup

3. Implement the OAuth Flow ​

Follow our Authorization Code Flow guide for step-by-step implementation instructions.

Security Considerations ​

Always Use HTTPS ​

All OAuth endpoints require HTTPS connections. HTTP requests will be rejected.

Implement PKCE for Public Clients ​

Single-page applications and mobile apps must use PKCE to protect against code interception attacks.

Secure Token Storage ​

  • Access tokens: Store in memory or secure session storage
  • Refresh tokens: Store in secure, encrypted storage
  • Never expose tokens: Don't include tokens in URLs or client-side code

Token Rotation ​

Refresh tokens are automatically rotated on each use. Always store the new refresh token after refreshing access tokens.

Rate Limits ​

To ensure service reliability, OAuth endpoints have the following rate limits:

  • Authorization endpoint: 20 requests per minute per user
  • Token endpoint: 60 requests per minute per client
  • User info endpoint: 120 requests per minute per user

Next Steps ​

Support ​

For OAuth integration support: