CitySDK Authentication: Methods and Best Practices (2026)

Authentication overview

CitySDK provides open-source tools and APIs designed for urban data integration and smart city development. Given its framework-oriented nature, authentication mechanisms within CitySDK are typically implemented at the module level or integrated with existing authentication systems of the platforms it connects to. This approach allows developers flexibility in securing their specific CitySDK deployments and data interactions. The core principles involve verifying the identity of a client or user before granting access to resources or performing actions.

The choice of authentication method within a CitySDK implementation often depends on the specific use case, the sensitivity of the data, and the architecture of the integrated systems. For direct API access, simple mechanisms like API keys are common, while scenarios requiring user consent or broader delegated access often leverage industry-standard protocols such as OAuth 2.0.

Understanding the authentication context for each CitySDK component is crucial for secure and functional deployments. Developers should consult the CitySDK official documentation for specific module-level authentication requirements and configuration details, as these can vary based on the particular service or data source being accessed.

Supported authentication methods

CitySDK, as a framework, supports or enables various authentication methods depending on the specific module, data source, or custom implementation. The most commonly encountered methods include API keys and OAuth 2.0. These methods are chosen based on the access pattern and security requirements of the application interacting with CitySDK components.

• API Keys: These are simple, unique identifiers used to authenticate an application or user without requiring a full login process. API keys are typically passed in the request header or as a query parameter. They are suitable for server-to-server communication or applications where the client's identity is sufficient for access control. While easy to implement, API keys require careful management to prevent unauthorized access.
• OAuth 2.0: This is an authorization framework that enables an application to obtain limited access to a user's protected resources on an HTTP service, without exposing the user's credentials to the client application. OAuth 2.0 is suitable for scenarios where a user grants permission for a third-party application to access their data, such as integrating CitySDK with citizen-facing applications. It provides various OAuth grant types to accommodate different application flows, including authorization code, client credentials, and implicit grants.
• Other Methods (Implementation Dependent): Depending on the specific deployment and integration with existing systems, CitySDK implementations may also support or be configured to use other authentication mechanisms, such as basic authentication or token-based authentication (e.g., JWTs) when integrated with custom backends or identity providers.

Authentication method comparison

Getting your credentials

As CitySDK is an open-source framework rather than a commercial service, the process for obtaining credentials differs from typical SaaS APIs. Credentials are not issued centrally by a single entity. Instead, they are generated or configured as part of your specific CitySDK deployment or when integrating with external data sources and services.

For API Keys:

1. Self-hosting CitySDK components: If you are deploying CitySDK modules that require API keys for external service access (e.g., mapping services, external data providers), you will typically obtain these keys directly from the respective third-party service providers. You then configure these keys within your CitySDK application's environment variables or configuration files.
2. Custom CitySDK API endpoints: If you are building your own APIs using CitySDK components and wish to secure them with API keys, you will need to implement a mechanism to generate, store, and validate these keys within your application. This often involves a database to store valid keys and a middleware to intercept and validate incoming requests.

For OAuth 2.0:

1. Registering your application: To use OAuth 2.0, your application must first be registered with the OAuth provider (e.g., Google, Facebook, a custom identity provider). This registration process typically involves providing your application's name, redirect URIs, and other relevant details. Upon successful registration, you will receive a Client ID and a Client Secret. These are your application's unique credentials for interacting with the OAuth provider.
2. Configuring CitySDK for OAuth: Integrate the obtained Client ID and Client Secret into your CitySDK application's configuration. This setup enables your application to initiate OAuth flows, request authorization from users, and exchange authorization codes for access tokens. The Google OAuth 2.0 documentation provides a comprehensive overview of the process for a common provider.

Always refer to the specific module's documentation within the CitySDK developer guides for precise instructions on credential setup, as configurations can vary significantly.

Authenticated request example

The exact structure of an authenticated request depends on the chosen method (API Key or OAuth 2.0) and the specific CitySDK module or endpoint being accessed. Below are conceptual examples demonstrating how credentials are typically included in HTTP requests.

Example with API Key (Header)

When using an API key, it is generally recommended to pass it in an HTTP header for better security compared to query parameters, as headers are less likely to be logged in web server access logs by default.

GET /api/v1/data/sensor_readings?city=Amsterdam HTTP/1.1
Host: your-citysdk-instance.com
Accept: application/json
X-API-Key: YOUR_API_KEY_HERE

In this example, YOUR_API_KEY_HERE would be replaced with the actual API key. The header name (e.g., X-API-Key, Authorization) might vary based on your CitySDK implementation or integrated service.

Example with OAuth 2.0 (Bearer Token)

For OAuth 2.0, after your application successfully completes the authorization flow and obtains an access token, this token is then included in the Authorization header using the Bearer scheme.

GET /api/v1/data/public_transport_routes?line=M52 HTTP/1.1
Host: your-citysdk-instance.com
Accept: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Here, YOUR_ACCESS_TOKEN_HERE represents the short-lived access token obtained from the OAuth provider. This token grants temporary access to protected resources on behalf of the user or client application.

Security best practices

Implementing robust security practices is critical when working with CitySDK, especially when dealing with urban data, which can include sensitive information. Adhering to these best practices helps protect your applications and the data they manage.

1. Use HTTPS/TLS for all communication: Always ensure that all communication with CitySDK endpoints and integrated services occurs over HTTPS. This encrypts data in transit, preventing eavesdropping and man-in-the-middle attacks. CitySDK deployments should enforce TLS 1.2 or higher.
2. Protect API Keys:
   • Environment Variables: Store API keys in environment variables rather than hardcoding them directly into your application's source code.
   • Access Control: Restrict access to systems and environments where API keys are stored or used.
   • Rotation: Regularly rotate API keys to minimize the impact of a compromised key.
   • Least Privilege: If possible, create API keys with the minimum necessary permissions for their intended use.
3. Manage OAuth 2.0 Tokens Securely:
   • Secure Storage: Store refresh tokens securely (e.g., in an encrypted database for server-side applications). Access tokens are typically short-lived and should not be persisted on the client-side beyond their expiry.
   • Short-lived Access Tokens: Use access tokens with short expiration times to limit the window of opportunity for attackers if a token is compromised.
   • Validate Redirect URIs: Ensure that your OAuth provider is configured with strict redirect URI validation to prevent authorization code interception attacks.
   • Proof Key for Code Exchange (PKCE): For public clients (e.g., mobile apps, SPAs), implement PKCE to mitigate authorization code interception attacks, as detailed in the RFC 7636 specification.
4. Input Validation and Output Encoding: Always validate all input received by your CitySDK-powered APIs to prevent injection attacks (e.g., SQL injection, XSS). Ensure that all output is properly encoded before being rendered to prevent client-side script execution.
5. Rate Limiting: Implement rate limiting on your API endpoints to prevent brute-force attacks and denial-of-service (DoS) attempts.
6. Logging and Monitoring: Implement comprehensive logging for authentication attempts, access failures, and other security-relevant events. Monitor these logs for suspicious activities and set up alerts for potential security incidents.
7. Regular Security Audits: Periodically conduct security assessments and penetration tests on your CitySDK deployments and integrated applications to identify and address vulnerabilities.
8. Stay Updated: Keep all CitySDK components, underlying frameworks, libraries, and operating systems up to date with the latest security patches to protect against known vulnerabilities.