Skip to content
This repository was archived by the owner on Feb 18, 2026. It is now read-only.

Latest commit

 

History

History
303 lines (246 loc) · 8 KB

cognito-test.mdx

File metadata and controls

303 lines (246 loc) · 8 KB
title description
AWS Cognito API Test
Test the AWS Cognito OAuth2 token endpoint

AWS Cognito API Test

This page demonstrates how to call the AWS Cognito OAuth2 token endpoint and test the authentication flow.

Configuration

Environment Setup

This project supports three environments. Configure your credentials for each environment:

Development Environment

Create .env.local file (excluded from version control):

# .env.local
NODE_ENV=development
COGNITO_DOMAIN=your-dev-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_dev_client_id
COGNITO_CLIENT_SECRET=your_dev_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=http://localhost:3000/v1

Staging Environment

Create .env.staging.local file (excluded from version control):

# .env.staging.local
NODE_ENV=staging
COGNITO_DOMAIN=your-staging-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_staging_client_id
COGNITO_CLIENT_SECRET=your_staging_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=https://staging-api.example.com/v1

Production Environment

Configure environment variables in your hosting platform:

# Production Environment Variables
NODE_ENV=production
COGNITO_DOMAIN=your-prod-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_prod_client_id
COGNITO_CLIENT_SECRET=your_prod_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=https://api.example.com/v1

Quick Setup

# Copy example file
cp env.example .env.local

# Edit with your actual credentials
nano .env.local

Test the API

API Documentation

The easiest way to understand the Cognito API is through the complete API documentation:

Direct Link: API Reference - OAuth2 Token Endpoint

This page provides:

  • Complete Specification: Full OpenAPI documentation
  • Code Examples: Copy cURL, JavaScript, and other examples
  • Response Schemas: Detailed request/response documentation
  • Environment Examples: Development, staging, and production configurations

Environment-Specific Testing

Development

# Option 1: Use the convenience script (recommended)
./start-dev.sh

# Option 2: Use npm directly
npm run dev

# Test with development credentials
curl -X POST "https://YOUR_DEV_COGNITO_DOMAIN/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_DEV_CLIENT_ID" \
  -d "client_secret=YOUR_DEV_CLIENT_SECRET" \
  -d "scope=cognito-api-scope"

Staging

# Start staging server
npm run dev:staging

# Test with staging credentials
curl -X POST "https://YOUR_STAGING_COGNITO_DOMAIN/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_STAGING_CLIENT_ID" \
  -d "client_secret=YOUR_STAGING_CLIENT_SECRET" \
  -d "scope=cognito-api-scope"

Production

# Start production server
npm run dev:prod

# Test with production credentials
curl -X POST "https://YOUR_PROD_COGNITO_DOMAIN/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_PROD_CLIENT_ID" \
  -d "client_secret=YOUR_PROD_CLIENT_SECRET" \
  -d "scope=cognito-api-scope"

1. Using cURL (Generic)

curl -X POST "https://YOUR_COGNITO_DOMAIN/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=cognito-api-scope"

2. Using JavaScript (Browser)

async function getCognitoToken() {
  const formData = new URLSearchParams();
  formData.append('grant_type', 'client_credentials');
  formData.append('client_id', 'YOUR_CLIENT_ID');
  formData.append('client_secret', 'YOUR_CLIENT_SECRET');
  formData.append('scope', 'cognito-api-scope');

  try {
    const response = await fetch('https://YOUR_COGNITO_DOMAIN/oauth2/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: formData,
    });

    const data = await response.json();
    
    if (response.ok) {
      console.log('Token received:', data);
      return data.access_token;
    } else {
      console.error('Error:', data);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
}

// Call the function
getCognitoToken();

3. Using Node.js

import fetch from 'node-fetch';

async function getCognitoToken() {
  const formData = new URLSearchParams();
  formData.append('grant_type', 'client_credentials');
  formData.append('client_id', 'YOUR_CLIENT_ID');
  formData.append('client_secret', 'YOUR_CLIENT_SECRET');
  formData.append('scope', 'cognito-api-scope');

  try {
    const response = await fetch('https://YOUR_COGNITO_DOMAIN/oauth2/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: formData,
    });

    const data = await response.json();
    
    if (response.ok) {
      console.log('Token received:', data);
      return data.access_token;
    } else {
      console.error('Error:', data);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
}

// Call the function
getCognitoToken();

Expected Response

Success Response (200)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cognito-api-scope"
}

Error Response (400/401)

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Using the Token

Once you have the access token, you can use it to make authenticated requests to your API:

// Example: Using the token to call a protected endpoint
const token = await getCognitoToken();

const response = await fetch('https://your-api.com/protected-endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

Environment Variables

Local Development

Create .env.local file (KEEP LOCAL - Never commit):

# .env.local
NODE_ENV=development
COGNITO_DOMAIN=your-dev-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_dev_client_id
COGNITO_CLIENT_SECRET=your_dev_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=http://localhost:3000/v1

Staging

Create .env.staging.local file (KEEP LOCAL - Never commit):

# .env.staging.local
NODE_ENV=staging
COGNITO_DOMAIN=your-staging-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_staging_client_id
COGNITO_CLIENT_SECRET=your_staging_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=https://staging-api.example.com/v1

Production Deployment

Set environment variables in your hosting platform:

# Production Environment Variables (Set in hosting platform)
NODE_ENV=production
COGNITO_DOMAIN=your-prod-cognito-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your_prod_client_id
COGNITO_CLIENT_SECRET=your_prod_client_secret
COGNITO_SCOPE=cognito-api-scope
API_BASE_URL=https://api.example.com/v1

Security Considerations

  • Version Control: Environment files are excluded from version control
  • Production Deployment: Use hosting platform environment variables
  • Credential Rotation: Implement regular secret rotation
  • Environment Isolation: Maintain separate credentials per environment

Troubleshooting

Common Issues

  1. Invalid Client Credentials: Check your client_id and client_secret
  2. Invalid Scope: Ensure the scope is properly configured in Cognito
  3. CORS Issues: Make sure your Cognito domain allows requests from your domain
  4. Network Issues: Check if the Cognito domain is accessible

Debug Steps

  1. Verify your Cognito configuration in AWS Console
  2. Test with cURL first to isolate issues
  3. Check browser network tab for detailed error messages
  4. Verify environment variables are loaded correctly