Skip to main content

OpenAPI Documentation

Authava provides comprehensive API documentation using the OpenAPI specification. This documentation allows you to explore and test the API endpoints directly from your browser.

Accessing the OpenAPI Documentation​

The OpenAPI documentation is available at:

https://api.authava.com/openapi

You can also access it from your dashboard by navigating to API Settings > API Documentation.

Understanding the API Structure​

The Authava API is organized into the following main sections:

Domains API​

Endpoints for managing authentication domains:

  • GET /api/v1/domains - List all domains
  • GET /api/v1/domains/{id} - Get domain details
  • POST /api/v1/domains - Create a new domain
  • PUT /api/v1/domains/{id} - Update a domain
  • DELETE /api/v1/domains/{id} - Delete a domain
  • POST /api/v1/domains/validate - Validate a domain
  • GET /api/v1/domains/verify - Verify domain DNS configuration

Users API​

Endpoints for managing users:

  • GET /api/v1/domains/{domainId}/users - List users for a domain
  • GET /api/v1/domains/{domainId}/users/{id} - Get user details
  • POST /api/v1/domains/{domainId}/users - Create a user
  • PUT /api/v1/domains/{domainId}/users/{id} - Update a user
  • DELETE /api/v1/domains/{domainId}/users/{id} - Delete a user

Email API​

Endpoints for managing email settings:

  • GET /api/v1/domains/{domainId}/email - Get email settings
  • PUT /api/v1/domains/{domainId}/email - Update email settings
  • POST /api/v1/domains/{domainId}/email/verify - Verify email configuration
  • POST /api/v1/smtp/verify - Verify SMTP settings
  • GET /api/v1/domains/{domainId}/email/templates - Get email templates
  • PUT /api/v1/domains/{domainId}/email/templates/{templateId} - Update email template

Social Providers API​

Endpoints for managing social login providers:

  • GET /api/v1/domains/{domainId}/social-providers - List social providers
  • POST /api/v1/domains/{domainId}/social-providers - Create a social provider
  • GET /api/v1/domains/{domainId}/social-providers/{id} - Get provider details
  • PUT /api/v1/domains/{domainId}/social-providers/{id} - Update a provider
  • DELETE /api/v1/domains/{domainId}/social-providers/{id} - Delete a provider

Authentication​

All API endpoints require authentication. You can authenticate using:

  1. API Key: Include your API key in the api-key header
  2. Bearer Token: Include a JWT token in the Authorization header

To get your API key:

  1. Go to Dashboard > API Settings
  2. Click Generate API Key
  3. Copy the generated key and store it securely

Example API request with authentication:

curl -X GET "https://api.authava.com/api/v1/domains" \
  -H "api-key: your_api_key_here"

Using the Interactive Documentation​

The OpenAPI documentation includes an interactive interface that allows you to:

  1. Explore Endpoints: Browse all available API endpoints with detailed descriptions
  2. Try Requests: Send test requests directly from the documentation
  3. View Responses: See example responses for each endpoint
  4. Understand Models: View the data models used by the API

To use the interactive documentation:

  1. Navigate to the OpenAPI documentation page
  2. Click on an endpoint to expand it
  3. Click the Try it out button
  4. Fill in the required parameters
  5. Click Execute to send the request
  6. View the response below

Downloading the OpenAPI Specification​

You can download the OpenAPI specification file to use with your own tools:

  1. JSON format: https://api.authava.com/openapi.json
  2. YAML format: https://api.authava.com/openapi.yaml

This specification can be imported into tools like Postman, Insomnia, or used with code generators to create client libraries.

Code Generation​

You can use the OpenAPI specification to generate client code for your preferred programming language:

  1. Download the OpenAPI specification file
  2. Use a tool like OpenAPI Generator to generate client code
  3. Integrate the generated code into your application

Example using the OpenAPI Generator CLI:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate a TypeScript client
openapi-generator-cli generate -i openapi.json -g typescript-fetch -o ./client

Rate Limiting​

The API has rate limits to prevent abuse:

  • Free tier: 100 requests per minute
  • Pro tier: 1000 requests per minute
  • Business tier: Custom limits

Rate limit headers are included in API responses:

  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in the current window
  • X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Error Handling​

The API uses standard HTTP status codes and returns detailed error messages:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid domain name format",
    "details": {
      "field": "domain",
      "constraint": "format"
    }
  }
}

Common error codes:

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation error
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Next Steps​

  • Explore the API documentation using the interactive interface
  • Use the OpenAPI specification to generate client code
  • Integrate the API with your application