Overview

API keys allow you to authenticate with the Groups.io application programming interface (API) without using your password. This feature allows users to generate, manage, and use API keys as an alternative to cookie-based authentication. Each key can be individually revoked if it is compromised.

Creating an API key

1. Display your account settings.
2. Desktop browser: In the left menu, select API Keys.
   Mobile device: Tap the More icon at the bottom of the page, then tap API Keys on the More menu.
   Tip: The direct link to the API Keys page is https://groups.io/settings/apikeys.
3. On the resulting page:
   • (Required) In the Key Name field, enter a descriptive name for the key (for example, CI/CD Pipeline or Mobile App).
   • (Optional but recommended) In the Description field, document the purpose of the key.
4. Click or tap Create API Key.
   The page refreshes and displays the full 64-character key in a green banner at the top of the page. The key name and description (if you provided one) are displayed in a table titled Your API Keys at the bottom of the page.
5. ! Important: Immediately copy and securely store the full key that is shown in the green banner. You will not be able to display it again.

Viewing API keys

1. Display your account settings.
2. Desktop browser: In the left menu, select API Keys.
   Mobile device: Tap the More icon at the bottom of the page, then tap API Keys on the More menu.
   Tip: The direct link to the API Keys page is https://groups.io/settings/apikeys.

Note: The full key is never shown again after creation.

Revoking or deleting an API key

You can revoke a key to disable it without deleting it, which preserves an audit trail. Deleting a key permanently removes it from the system.

To revoke or delete an API key:

1. Display your account settings.
2. Desktop browser: In the left menu, select API Keys.
   Mobile device: Tap the More icon at the bottom of the page, then tap API Keys on the More menu.
   Tip: The direct link to the API Keys page is https://groups.io/settings/apikeys.
3. In the key’s row in the Your API Keys table, click or tap the Revoke or Delete button (as applicable).
4. When the confirmation popup appears, click or tap OK.

Best practices for end users

• Key generation
  • Use descriptive names. Examples: CI/CD Pipeline, Mobile App
  • Add descriptions to remember the keys’ purpose.
  • Store keys immediately because they cannot be retrieved later.
• Key storage
  • Never share API keys via email or chat.
  • Use environment variables in applications.
  • Consider using secrets management tools.
• Key rotation
  • Generate new keys before revoking old ones.
  • Update applications with new keys.
  • Monitor last used dates to identify unused keys.
• Security
  •  Treat API keys like passwords.
  •  Revoke compromised keys immediately.
  •  Delete unused keys regularly

Best practices for developers

• Using API keys

  ```bash
 curl -H "Authorization: Bearer YOUR_API_KEY" https://groups.io/api/v1/getsubs
```

• Error handling
  • Check for 401 Unauthorized responses.
  • Implement key rotation in applications.
  • Log API errors for debugging. Never log the key itself.
• Migration from cookie authentication
  • API keys provide stateless authentication.
  • Better for automated systems and CI/CD.
  • No session management required.

Technical architecture

• Database schema

  API keys are stored in the 'apikeys' table with the following structure:

  • id: Unique identifier for the API key
  • userid: ID of the user who owns the key
  • name: User-defined name for the key (required)
  • description: Optional description of the key's purpose
  • keyprefix: First 8 characters of the key for efficient database lookups
  • keyhash: BCrypt hash of the full key for secure storage
  • status: Active (0) or Revoked (1)
  • lastused: Timestamp of last API call using this key
  • expiresat: Optional expiration date (if not set, key never expires)
  • created/updated/version: Standard audit fields
• Key generation and storage
  • Keys are 64 characters long (32 random bytes converted to hexadecimal).
  • The full key is shown only once during creation.
  • Keys are stored using BCrypt hashing (same security as passwords).
  • First 8 characters are stored as plaintext for efficient lookup.
  • Keys cannot be recovered if lost. Users must generate new ones.
• Authentication flow
  1. Client includes API key in the 'Authorization' header as a Bearer token:
     ```
   Authorization: Bearer [64-character-api-key]
```
  2. Server extracts the key prefix (first 8 chars) for database lookup.
  3. Server retrieves potential matching keys from database.
  4. Server verifies the full key against the BCrypt hash.
  5. If valid and active, the associated user is authenticated.
  6. Last used timestamp is updated asynchronously.

Security considerations

• Key security
  • Keys have same authentication power as passwords.
  • Keys should be stored securely (environment variables, secrets management).
  • Never commit keys to version control.
  • Rotate keys periodically.
• Status management
  • Active keys can authenticate API requests.
  • Revoked keys are disabled but retained for audit purposes.
  • Expired keys (if expiration is set) automatically become inactive.
• Usage tracking

  Last used timestamp:

  • Helps identify inactive keys.
  • Can be used to detect unauthorized usage.
  • Assists in key rotation decisions.

API implementation

• Authentication priority

  The API server checks authentication in this order:

  1. API key in Authorization header (if present)
  2. Cookie-based authentication (existing method)
• Supported endpoints

  All existing API endpoints that require authentication support API key authentication. No changes to endpoint behavior; only the authentication method differs.

• Error handling
  • Invalid/missing API key returns standard authentication error.
  • Revoked keys return authentication error.
  • Expired keys return authentication error.
  • No distinction in error messages (security through obscurity).

Limitations and considerations

• No scope limitations: API keys have full access to all of the user's permissions (same as logging in).
• No IP restrictions: Keys can be used from any IP address.
• No rate limiting: Per-key rate limiting is not implemented (uses existing user rate limits).
• Single user association: Each key belongs to exactly one user.
• No automatic expiration: Keys do not expire unless they are explicitly set to do so.