Authentication Service

The Authentication Service helps you add secure user authentication to your application. Whether you're building a web app, mobile app, or API, this service handles all the complex security details for you.

What you can do:

  • Let users create accounts and log in with email/password
  • Keep users logged in across sessions with automatic token refresh
  • Send password reset emails and verify user emails
  • Manage user profiles and session security

Interactive API Reference

For complete API documentation with interactive testing, visit our Swagger UI where you can try all endpoints with your own credentials.

View Interactive API Docs

Register a New User

This is typically the first step when a new user signs up for your application. You'll receive authentication tokens that allow the user to immediately access protected features without having to log in separately. 

curl -X POST https://auth.stackfordevs.com/v1/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "metadata": {
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

Response:

{
  "user": {
    "id": "usr_abc123...",
    "email": "user@example.com",
    "emailVerified": false,
    "metadata": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "createdAt": "2025-10-31T12:00:00.000Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_xyz789..."
}

Important: Store both the accessToken (for API requests) and refreshToken (for getting new access tokens when they expire). The access token expires in 15 minutes, while the refresh token lasts 30 days.

Login User

When a returning user wants to access your application, they'll use this endpoint to log in. Just like registration, you'll receive fresh authentication tokens. 

curl -X POST https://auth.stackfordevs.com/v1/login \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Response:

{
  "user": {
    "id": "usr_abc123...",
    "email": "user@example.com",
    "emailVerified": true,
    "metadata": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_xyz789..."
}

Refresh Access Token

Access tokens expire after 15 minutes for security. When this happens, use your refresh token to get a new access token without requiring the user to log in again. This keeps users logged in seamlessly. 

curl -X POST https://auth.stackfordevs.com/v1/refresh-token \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "refreshToken": "rt_xyz789..."
  }'

Response:

{
  "user": {
    "id": "usr_abc123...",
    "email": "user@example.com",
    "emailVerified": true,
    "metadata": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_new456..."
}

Note: The refresh token gets rotated (changed) each time you use it for enhanced security. Always store the new refresh token and discard the old one.

Get Current User Profile

Retrieve the profile information for the currently authenticated user. This is useful for displaying user information in your app, or verifying that an access token is still valid. 

curl -X GET https://auth.stackfordevs.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "user": {
    "id": "usr_abc123...",
    "email": "user@example.com",
    "emailVerified": true,
    "metadata": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "createdAt": "2025-10-31T12:00:00.000Z"
  }
}

Important: This endpoint uses Bearer token authentication (not API keys). Include the access token in the Authorization header as shown above.

Request Password Reset

When a user forgets their password, this endpoint sends them a password reset email with a secure token. The email will contain a link they can click to reset their password. 

curl -X POST https://auth.stackfordevs.com/v1/forgot-password \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "user@example.com"
  }'

Response:

{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent"
}

Complete Password Reset

After the user receives the reset email and clicks the link, use this endpoint to actually change their password. The token comes from the email link. 

curl -X POST https://auth.stackfordevs.com/v1/reset-password \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePassword123!"
  }'

Response:

{
  "success": true,
  "message": "Password reset successfully"
}

Note: Reset tokens expire after 1 hour for security. If the token has expired, the user will need to request a new reset email.

Verify User Email

If your project requires email verification, users will receive a verification email when they register. This endpoint confirms their email address using the token from that email. 

curl -X POST https://auth.stackfordevs.com/v1/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verify_token_from_email"
  }'

Response:

{
  "success": true,
  "message": "Email verified successfully"
}

Resend Verification Email

If the verification email was lost or expired, use this endpoint to send a new one to the user. 

curl -X POST https://auth.stackfordevs.com/v1/resend-verification \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "user@example.com"
  }'

Response:

{
  "success": true,
  "message": "Verification email sent"
}

Logout User

When a user logs out, this invalidates all of their refresh tokens. Any existing access tokens will remain valid until they expire (15 minutes), but new tokens cannot be obtained. 

curl -X POST https://auth.stackfordevs.com/v1/logout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "refreshToken": "rt_xyz789..."
  }'

Response:

{
  "success": true
}

Error Handling

All errors follow a consistent format: 

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

Common Error Codes:

  • INVALID_CREDENTIALS - Email or password is incorrect
  • USER_ALREADY_EXISTS - Email is already registered
  • INVALID_SESSION - Session token is invalid or expired
  • UNAUTHORIZED - Invalid API credentials
  • VALIDATION_ERROR - Request validation failed