Authentication

Overview

The EcoEvents API uses API keys and JWT tokens for authentication. All API requests must be authenticated to protect your data and ensure secure access to our platform.

Never share your API keys or commit them to version control. Treat them like passwords and store them securely using environment variables or a secrets manager.

Authentication Methods

EcoEvents supports two authentication methods:

1. API Keys (Recommended for Server-to-Server)

API keys are ideal for server-side applications and long-running services. They don’t expire unless manually revoked.

2. JWT Tokens (Recommended for Client Applications)

JWT tokens are short-lived (24 hours) and ideal for client-side applications. They can be refreshed using refresh tokens.

Obtaining API Keys

Creating an API Key

Log in to your EcoEvents Dashboard
Navigate to Settings > API Keys
Click Create New API Key
Provide a descriptive name (e.g., “Production Server”, “Staging Environment”)
Select the appropriate permissions scope
Copy the key immediately (it won’t be shown again)

API keys are displayed only once during creation. Store them securely in your environment variables or secrets manager. If you lose a key, you’ll need to create a new one.

API Key Scopes

When creating an API key, you can limit its permissions:

Scope	Description
`events:read`	Read event data
`events:write`	Create and update events
`events:delete`	Delete events
`analytics:read`	Access sustainability analytics
`vendors:read`	View vendor information
`vendors:write`	Manage vendor relationships
`webhooks:manage`	Configure webhooks
`full_access`	Complete account access

Follow the principle of least privilege. Only grant the minimum permissions required for your application to function.

Obtaining JWT Tokens

JWT tokens are obtained by authenticating with your account credentials:

curl -X POST "https://api.ecoevents.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_secure_password"
  }'

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_1a2b3c4d5e6f7g8h9i0j",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}

Refreshing JWT Tokens

When your access token expires, use the refresh token to obtain a new one:

curl -X POST "https://api.ecoevents.com/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_1a2b3c4d5e6f7g8h9i0j"
  }'

Including Authentication in Requests

Using API Keys

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET "https://api.ecoevents.com/v1/events" \
  -H "Authorization: Bearer ek_live_1a2b3c4d5e6f7g8h9i0j"

Using JWT Tokens

JWT tokens are included in the same way as API keys:

curl -X GET "https://api.ecoevents.com/v1/events" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Testing API Keys

Test your API key by calling the authentication verification endpoint:

curl -X GET "https://api.ecoevents.com/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

{
  "valid": true,
  "key": {
    "id": "key_1a2b3c4d5e",
    "name": "Production Server",
    "scopes": ["events:read", "events:write", "analytics:read"],
    "createdAt": "2026-01-15T10:30:00Z",
    "lastUsed": "2026-03-05T14:22:00Z"
  },
  "account": {
    "id": "acc_9i8h7g6f5e",
    "name": "Green Events Co.",
    "tier": "professional"
  }
}

Security Best Practices

1. Store Credentials Securely

Never hardcode API keys or tokens in your source code. Use environment variables, secrets managers, or secure configuration files.

Good Practice:

// Use environment variables
const apiKey = process.env.ECOEVENTS_API_KEY;

Bad Practice:

// Never do this!
const apiKey = 'ek_live_1a2b3c4d5e6f7g8h9i0j';

2. Use HTTPS Only

Always use HTTPS for API requests. The EcoEvents API will reject plain HTTP requests.

3. Rotate Keys Regularly

Rotate your API keys periodically (e.g., every 90 days) and immediately if you suspect they’ve been compromised.

4. Use Appropriate Scopes

Grant only the minimum permissions required. If your application only reads events, use events:read instead of full_access.

5. Monitor API Key Usage

Regularly review API key usage in your dashboard. Revoke any keys that are no longer needed or show suspicious activity.

6. Implement Token Refresh Logic

For JWT-based authentication, implement automatic token refresh to handle expiration gracefully.

7. Handle Authentication Errors

Always handle 401 Unauthorized responses appropriately:

const response = await fetch('https://api.ecoevents.com/v1/events', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (response.status === 401) {
  console.error('Authentication failed. Check your API key.');
  // Handle re-authentication or notify user
}

8. Use Test Keys in Development

EcoEvents provides separate test API keys (prefixed with ek_test_) for development. These keys work with sandbox data and won’t affect production.

Test API keys have the same format as live keys but are prefixed with ek_test_ instead of ek_live_. Use them during development to avoid affecting production data.

9. Implement Rate Limiting

Implement client-side rate limiting to stay within your tier’s limits and avoid 429 Too Many Requests errors.

10. Log Authentication Events

Log authentication attempts and failures for security monitoring and debugging.

Revoking API Keys

If an API key is compromised or no longer needed:

Log in to your EcoEvents Dashboard
Navigate to Settings > API Keys
Find the key you want to revoke
Click Revoke and confirm

Revoking an API key immediately invalidates it. All requests using the revoked key will return 401 Unauthorized. Update your applications before revoking keys currently in use.

OAuth 2.0 (Coming Soon)

We’re developing OAuth 2.0 support for third-party integrations. This will allow users to authorize your application without sharing their credentials. Interested in beta access? Contact [email protected].

Troubleshooting

401 Unauthorized

Causes:

Invalid or expired API key
Expired JWT token
Missing Authorization header
Incorrect authorization format

Solution:

Verify your API key is correct
Refresh your JWT token
Ensure the header format is Authorization: Bearer YOUR_KEY

403 Forbidden

Causes:

Insufficient permissions for the requested operation
API key scope doesn’t include required permission

Solution:

Check the API key scopes in your dashboard
Create a new key with appropriate permissions

Token Refresh Fails

Causes:

Refresh token expired (30 days)
Refresh token already used
Account password changed

Solution:

Re-authenticate with username and password
Obtain new access and refresh tokens

Support

Need help with authentication? Contact our support team:

Email: [email protected]
Documentation: https://docs.ecoevents.com/api/authentication
Security Issues: [email protected]

For security vulnerabilities, please email [email protected] directly. We have a responsible disclosure program and typically respond within 24 hours.

Overview

Endpoints

Overview

Authentication Methods

1. API Keys (Recommended for Server-to-Server)

2. JWT Tokens (Recommended for Client Applications)

Obtaining API Keys

Creating an API Key

API Key Scopes

Obtaining JWT Tokens

Response

Refreshing JWT Tokens

Including Authentication in Requests

Using API Keys

Using JWT Tokens

Testing API Keys

Success Response

Security Best Practices

1. Store Credentials Securely

2. Use HTTPS Only

3. Rotate Keys Regularly

4. Use Appropriate Scopes

5. Monitor API Key Usage

6. Implement Token Refresh Logic

7. Handle Authentication Errors

8. Use Test Keys in Development

9. Implement Rate Limiting

10. Log Authentication Events

Revoking API Keys

OAuth 2.0 (Coming Soon)

Troubleshooting

401 Unauthorized

403 Forbidden

Token Refresh Fails

Support

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Authentication Methods

​1. API Keys (Recommended for Server-to-Server)

​2. JWT Tokens (Recommended for Client Applications)

​Obtaining API Keys

​Creating an API Key

​API Key Scopes

​Obtaining JWT Tokens

​Response

​Refreshing JWT Tokens

​Including Authentication in Requests

​Using API Keys

​Using JWT Tokens

​Testing API Keys

​Success Response

​Security Best Practices

​1. Store Credentials Securely

​2. Use HTTPS Only

​3. Rotate Keys Regularly

​4. Use Appropriate Scopes

​5. Monitor API Key Usage

​6. Implement Token Refresh Logic

​7. Handle Authentication Errors

​8. Use Test Keys in Development

​9. Implement Rate Limiting

​10. Log Authentication Events

​Revoking API Keys

​OAuth 2.0 (Coming Soon)

​Troubleshooting

​401 Unauthorized

​403 Forbidden

​Token Refresh Fails

​Support

Build docs developers (and LLMs) love

Overview

Authentication Methods

1. API Keys (Recommended for Server-to-Server)

2. JWT Tokens (Recommended for Client Applications)

Obtaining API Keys

Creating an API Key

API Key Scopes

Obtaining JWT Tokens

Response

Refreshing JWT Tokens

Including Authentication in Requests

Using API Keys

Using JWT Tokens

Testing API Keys

Success Response

Security Best Practices

1. Store Credentials Securely

2. Use HTTPS Only

3. Rotate Keys Regularly

4. Use Appropriate Scopes

5. Monitor API Key Usage

6. Implement Token Refresh Logic

7. Handle Authentication Errors

8. Use Test Keys in Development

9. Implement Rate Limiting

10. Log Authentication Events

Revoking API Keys

OAuth 2.0 (Coming Soon)

Troubleshooting

401 Unauthorized

403 Forbidden

Token Refresh Fails

Support