API Key Authentication & External APIs
Relevant source files
The following files were used as context for generating this wiki page:
API Key Authentication provides programmatic access to GoGovSG services. It allows authorized users to generate and manage short links through external and admin-level APIs rather than the web interface.
The system secures these requests using a hashed API key validation mechanism. This ensures that only authenticated government officers can interact with the link-shortening engine programmatically.
System Configuration
The API system relies on several environment variables and constants to manage security and feature availability. The feature flag FF_EXTERNAL_API must be true to enable both external and admin APIs.
| Variable | Type | Description |
|---|---|---|
API_KEY_SALT | String | Used to generate and hash API keys. |
FF_EXTERNAL_API | Boolean | Enables or disables external/admin API endpoints. |
API_KEY_VERSION | String | Defines the current version of the API (defaults to v1). |
ADMIN_API_EMAILS | String[] | Comma-separated list of emails authorized for admin API access. |
Sources: src/server/config.ts:257-263, README.md:143-154
The system uses a specific separator to structure the API key components.
Sources: src/server/constants.ts:117
API Key Management
Users manage their keys through the "API Integration" page in the client application. If a user does not have a key, the system displays a generation interface.
Generation Flow
- You click the "Generate API Key" button on the API Integration page.
- The client dispatches
apiActions.generateApiKey(). - The server creates a random key and hashes it using
API_KEY_SALT. - The server stores the hashed value and returns the plaintext key to the user exactly once.
Key Validation
The server validates incoming requests by checking the Authorization header. It hashes the provided key and compares it against the stored hash in the database.
External API (v1)
The External API allows standard users to perform CRUD operations on their own links. It specifically supports HTTPS URLs.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/urls | Retrieves all URLs created by the authenticated user. |
POST | /api/v1/urls | Creates a new short link for the user. |
PATCH | /api/v1/urls/:shortUrl | Updates the longUrl or state of an existing link. |
Sources: test/integration/api/external-v1/Urls.test.ts:74-166
Link Creation Requirements
When creating a link via the API:
- The
longUrlis required. - Only
HTTPSURLs are accepted; the system returns aValidationErrorotherwise. - The
shortUrlis optional; if omitted, the system generates a random string of lengthAPI_LINK_RANDOM_STR_LENGTH(defaults to 8).
Sources: test/integration/api/external-v1/Urls.test.ts:110-145, src/server/config.ts:259
Admin API (v1)
The Admin API provides extended capabilities for authorized administrative users. Access is strictly limited to emails defined in the ADMIN_API_EMAILS configuration.
Administrative Link Creation
The Admin API enables the creation of links on behalf of other users. Unlike the standard External API, the POST /api/admin/v1/urls endpoint requires an email field. This email must belong to a whitelisted domain.
Client Implementation
The frontend utilizes React and Redux to handle API integration state. The ApiIntegrationPage component determines whether to show key generation graphics or existing key information based on the hasApiKey state.
Components
- ApiIntegrationPage: Main container that dispatches
apiActions.hasApiKey()on mount. - NoApiKeyGraphic: Renders a prompt and a "Generate API Key" button when no key exists.
- ApiKeyModal: Handles the display and copying of a newly generated key.
Sources: src/client/apiintegration/index.tsx:44-53, src/client/apiintegration/components/NoApiKeyGraphic/index.tsx:55-75
Summary
The API Key Authentication and External API module enables secure, programmatic interaction with GoGovSG. By combining environment-driven security (salts and feature flags) with a dedicated management UI and versioned endpoints (v1), the system allows government agencies to automate link creation while maintaining strict anti-phishing and authorization standards.