API Keys

Introduction

SOASAP SDKs use API keys to authenticate with SOASAP Cloud and synchronize feature flag configuration. An API key connects an SDK instance to a specific configuration scope: one project environment.

API keys are used during:

• SDK initialization
• initial configuration synchronization
• SSE connection establishment
• background reconnection
• snapshot refresh

API keys are not used for each local flag evaluation. Once a snapshot has been loaded, flag reads occur from local SDK state. See Local Evaluation.

API key mental model

The key identifies which configuration an SDK may synchronize. The key does not determine application-user identity or application authorization.

API keys authenticate SDK clients. Feature flags do not replace application authentication or authorization.

What API keys are used for

SDK API keys are used to:

• identify an SDK client
• select the intended project and environment
• authenticate synchronization requests
• establish or restore the synchronization channel
• retrieve the configuration snapshot associated with the key’s scope

They are not:

• end-user access tokens
• OAuth tokens
• session cookies
• database credentials
• encryption keys
• administrator passwords
• authorization rules for product users
• a substitute for server-side access control

Environment-scoped keys

Each SOASAP environment has one SDK API key. Use that environment’s key only in deployments that should consume that environment’s configuration.

Environment isolation:

• prevents development builds from receiving production values
• reduces the blast radius of a leaked credential
• supports independent rotation per environment
• avoids accidental cross-environment synchronization
• makes deployment configuration easier to audit
• keeps cache identity and configuration scope predictable

Project boundaries

Keys remain aligned with the project and environment for which they were created. Do not reuse one credential across unrelated products, services, business units, tenants, development teams, or deployment environments that should not share configuration.

Credential boundaries should follow operational ownership and configuration scope. If multiple services intentionally consume the same project and environment, document that dependency and its shared rotation procedure — those services share one environment key.

Creating an API key

SOASAP creates an SDK API key when an environment is created. Owners and Admins manage keys from the dashboard API Keys area.

Typical workflow:

1. Open the intended SOASAP organization and project.
2. Open API Keys.
3. Select the project and locate the required environment.
4. Copy the environment SDK key into an approved secret-management system.
5. Configure the application deployment with that secret.
6. Verify SDK synchronization.
7. Remove temporary local copies.

Key display and copying

The dashboard shows a truncated preview of each environment key and allows copying the full value. Treat every reveal or copy as a secret-handling event.

Recommend:

• copy it directly into a secret manager
• avoid pasting it into chat, tickets, documents, or source files
• do not capture it in screenshots
• clear temporary clipboard history where organizational policy requires it
• avoid leaving it in terminal scrollback
• do not send it through email or general-purpose messaging

Configuring an SDK

Conceptual initialization:

soasap = createClient({
  apiKey: configuration.soasapApiKey
})

The exact constructor, option name, dependency injection pattern, and lifecycle depend on the SDK. See SDK Installation and the platform-specific SDK pages.

Server-side applications

Store the key in:

• a managed secret store
• an environment variable injected by the deployment platform
• a protected configuration provider
• a container or orchestrator secret
• a platform-approved encrypted configuration system

Recommend:

• create one long-lived SDK client per required configuration scope
• load the key during application initialization
• do not print the key in startup logs
• do not include it in diagnostics endpoints
• do not serialize it into persistent cache
• do not return it to frontend code

A server-side key should remain inside the trusted server environment.

Environment variables

SOASAP_SDK_KEY=<environment-sdk-key>

Environment variables are commonly used for deployment-time injection, but they are not automatically secure. Risks may include accidental diagnostic dumps, process inspection, CI/CD logs, shell history, broad host access, and inherited child-process environments.

Recommend:

• use platform secret injection
• mask values in logs
• limit access to the runtime identity
• avoid committing .env files
• use separate local-development and production configuration

Secret managers

Production keys should preferably be managed through the organization’s existing secret-management infrastructure. Examples may include AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, Kubernetes Secrets with appropriate controls, and managed deployment-platform secrets.

SOASAP does not require a specific provider. Desired properties include access control, encryption at rest, deployment-time retrieval, versioning, rotation workflows, auditability, and reduced direct human access.

Containers

Inject keys at runtime. Do not place credentials in Dockerfiles, container image layers, image build arguments, committed .env files, public container registries, or application artifacts.

A secret removed from a later image layer may still remain in the image history.

Kubernetes

Use Kubernetes Secrets, an approved external-secrets controller, workload-integrated secret retrieval, and namespace and RBAC controls.

Recommend:

• separate Secrets by environment
• restrict which service accounts may read them
• avoid exposing Secret values through ConfigMaps
• verify volume or environment-variable updates during rotation
• account for Pod rollout behavior
• ensure Production namespaces never consume Development credentials

CI/CD pipelines

Build systems should not require Production SDK keys when the key is needed only at runtime.

Avoid:

• embedding keys during frontend compilation
• printing secrets in pipeline output
• passing keys as unmasked command-line arguments
• storing keys in generated manifests committed to Git
• exposing keys to untrusted pull-request workflows

Prefer environment-specific deployment approvals for Production credentials.

Local development

Developers should use a Development environment key. Recommended approaches include local secret storage, user-level environment variables, ignored .env files, development secret stores, and platform-specific local secret tooling.

Ignore local environment files in source control. A .gitignore entry reduces accidental commits; it is not complete secret protection.

.env
.env.local
.env.*.local

Web applications

Anything delivered to a browser can be inspected through JavaScript bundles, browser developer tools, source maps, network requests, browser extensions, and cached assets.

Mobile applications

Keys compiled into distributed mobile applications cannot be considered secret. Attackers may inspect Android packages, iOS bundles, application memory, network traffic, decompiled code, and configuration resources.

Recommend:

• assume embedded credentials are discoverable
• use server-side evaluation for sensitive decisions
• rotate exposed keys when a distributed credential is compromised
• keep flag payloads free of secrets
• maintain server-side authorization regardless of feature state

Public clients vs trusted servers

The appropriate key strategy depends on whether the runtime is controlled by the organization or distributed to end users.

API keys and feature flag security

Feature flags control application behavior but must not be the sole enforcement mechanism for sensitive operations.

Do not rely on a flag alone to:

• grant administrative access
• authorize payments
• expose private customer records
• enforce subscription entitlements
• protect privileged API routes
• replace server-side permission checks

Even when a user interface hides a feature, the server must independently enforce authorization.

Key inventory

Maintain an inventory of active keys and their deployment purpose. Recommended operational metadata (often maintained outside SOASAP):

• project
• environment
• consuming service
• deployment platform
• owning team
• creation date
• last rotation date
• rotation owner
• expected retirement date
• incident contact

Key identification

SOASAP binds one key to each environment. Identify credentials by project and environment name in secret stores and inventories, for example:

• soasap/production/api
• soasap/production/workers only when those deployments share the Production environment key intentionally
• soasap/staging/web
• soasap/development/local

Avoid embedding sensitive infrastructure details in public labels. Track per-service deployment identity externally when several services share one environment key.

Rotation overview

In SOASAP, rotating an environment key regenerates it. The previous key is permanently invalidated when regeneration completes. There is one active SDK key per environment at a time.

Reasons to rotate include:

• suspected exposure
• confirmed compromise
• personnel or vendor changes
• policy requirements
• environment restructuring
• migration between secret systems
• accidental logging
• repository exposure

Coordinated rotation

Because regeneration invalidates the previous key immediately, plan the rollout so deployments receive the new key as quickly as possible. Application request handling can continue from local snapshots, but configuration freshness stops advancing for any instance still using the old key.

Step-by-step procedure:

1. Identify every service, region, job, and deployment slot that uses the environment key.
2. Prepare secret-manager updates and deployment pipelines for the replacement value.
3. In the dashboard, open API Keys and regenerate the environment key.
4. Copy the new key into the approved secret system immediately.
5. Roll out the new key to all consumers as quickly as operationally safe.
6. Confirm that instances authenticate and synchronize with the new key.
7. Confirm workers, inactive slots, and disaster-recovery deployments were updated.
8. Monitor authentication failures and disconnected instances.
9. Remove retired secret versions from deployment systems where policy allows.

Local evaluation may continue during the migration window, but dashboard changes will not reach instances that still present the invalidated key.

Rotation across a fleet

Large deployments may include multiple services, regions, Kubernetes clusters, workers, scheduled jobs, autoscaling groups, inactive deployment slots, disaster-recovery environments, and long-running processes.

Track migration progress by deployment group. Do not consider rotation complete after validating only one instance. All consumers must be identified and updated.

Rotation and running SDK instances

An SDK already holding a valid local snapshot may continue local evaluation after its previous credential is invalidated. However:

• reconnection may fail
• configuration freshness may stop advancing
• a restart may require the replacement key
• dashboard changes may not propagate to the affected instance

Rotation and persistent cache

Persistent cache may restore an older snapshot after restart, but it does not fix invalid authentication. Operators must verify both snapshot restoration and successful authentication with the replacement key. See Persistent Cache and Cache Strategy.

If a deployment moves to a different project or environment, use a separate cache path rather than reusing the previous environment’s cache location.

Emergency rotation

1. Identify the exposed key.
2. Determine its project and environment scope.
3. Identify all consuming deployments.
4. Regenerate the environment key in the dashboard.
5. Deploy the replacement immediately.
6. Verify successful synchronization.
7. Monitor for failed authentication and disconnected instances.
8. Remove the key from logs, repositories, artifacts, and secret stores where possible.
9. Review the exposure path.
10. Record the incident and preventive actions.

If active abuse is suspected, regenerate immediately even if some instances have not yet been prepared. Immediate invalidation reduces security exposure but interrupts synchronization for any instance that has not yet received the new key.

Invalidation after rotation

Regenerating an environment key permanently invalidates the previous value for future authenticated communication. Use regeneration when:

• a key is leaked
• rotation is required by policy
• personnel or vendor access changes
• a key was used for the wrong operational purpose and must be replaced

Expected impact after the previous key is invalidated:

• new SDK authentication using the old key fails
• reconnect attempts using the old key fail
• new snapshot synchronization stops for those clients
• running SDKs may continue evaluating their current local snapshot
• restarted instances may restore cache or use defaults, but cannot refresh until configured with the current key

Exact reconnect timing depends on connection state and SDK implementation. See Real-Time Synchronization.

Product action: regenerate

SOASAP’s dashboard action is Rotate Key / regenerate. That action:

• creates a new environment SDK key
• permanently invalidates the previous key
• returns the new key for immediate secure storage and deployment
• is available to Owners and Admins

There is no separate dual-active-key window. Treat regenerate as both rotation and invalidation of the prior credential.

Lost key

If the key value is no longer available in an approved secret store:

• do not recover it from logs or source history
• copy it again from the dashboard if it is still the current environment key, or regenerate if exposure is suspected
• update the deployment secret
• verify synchronization
• if the previous value may still be active elsewhere after regeneration, treat remaining copies as compromised

Leaked key

Common leak channels:

• Git commits
• package registries
• container images
• CI logs
• browser bundles
• mobile binaries
• screenshots
• support tickets
• chat messages
• shell history
• observability payloads
• crash reports

Treat the key as compromised even if the exposure was brief or later removed. Deleting a key from Git history or a message does not prove that no copy exists.

Source control exposure

1. Remove the key from current source.
2. Regenerate the exposed environment key.
3. Update affected deployments.
4. Scan repository history and forks.
5. Check CI logs and artifacts.
6. Review whether the repository was cloned externally.
7. Add automated secret scanning.
8. Document the incident.

Removing the plaintext value from the latest commit is not sufficient.

Logging and redaction

Never log:

• full API keys
• authorization headers
• complete SDK configuration objects containing credentials
• secret environment-variable dumps
• request URLs containing credentials

Safe diagnostic information may include:

• authentication succeeded or failed
• environment identifier
• error category
• last successful synchronization time
• connection status

Observability

Recommend monitoring:

• authentication failures
• invalid-key errors
• authorization failures
• SSE connection status
• time since last successful synchronization
• reconnect attempts
• instances using a retired deployment configuration
• sudden fleet-wide disconnects after rotation
• new instances unable to initialize
• environment mismatches
• unexpected default fallbacks after restart

Key health is primarily visible through synchronization behavior. Local evaluation may continue while authentication remains broken.

Validating a key

1. Configure the key in a non-production test instance.
2. Start the SDK.
3. Confirm authentication succeeds.
4. Confirm the expected environment snapshot is received.
5. Evaluate a known non-sensitive test flag.
6. Confirm synchronization remains connected.
7. Restart the instance.
8. Confirm authentication and cache behavior remain correct.

Invalid API key behavior

Possible symptoms:

• initial synchronization does not complete
• SSE authentication fails
• reconnect attempts continue
• no new snapshot arrives
• cached values continue after restart where available
• explicit defaults are used when no snapshot exists
• application health may remain otherwise normal

An invalid key is not the same as a SOASAP Cloud outage, DNS failure, TLS failure, firewall block, or cache restoration failure. See Invalid API Key.

Wrong-environment key

A syntactically valid key may still be operationally incorrect when it belongs to another environment. Possible symptoms:

• unexpected flag values
• missing expected flags
• production-like behavior in staging
• staging configuration in production
• cache confusion after deployment changes

Recommended response:

• confirm the intended project and environment
• check deployment secret references
• verify namespace, account, or pipeline environment
• use separate secret names for each environment
• avoid generic secret identifiers such as soasap-key across all deployment targets

Do not expose full key values while comparing configuration.

Key rotation failure scenarios

New key deployed to only part of the fleet

Some instances authenticate with the new key; others still depend on the invalidated key and lose synchronization. Complete the rollout and monitor disconnects by deployment group.

Secret updated but processes not restarted or reloaded

Running applications may continue using the old in-memory credential. Reload or roll out processes according to the deployment platform.

New key belongs to the wrong environment

Instances may authenticate successfully but receive incorrect configuration. Correct the secret mapping and verify expected flags.

Inactive workloads missed

Scheduled jobs or disaster-recovery deployments fail later. Include inactive and secondary consumers in the inventory before regenerating.

Cache masks authentication failure

Local evaluation continues, delaying detection of a broken credential. Monitor synchronization status and time since last successful sync separately from request success.

Regeneration before consumers are ready

All instances lose refresh capability until updated. Acceptable for emergency compromise response; avoid for routine rotation without a prepared rollout plan.

Failure-scenario table

Production rotation runbook

Rotation owner:
Project:
Environment:
Current key identifier (non-secret label):
Replacement key identifier (non-secret label):
Reason for rotation:
Affected services:
Affected regions or clusters:
Secret stores updated:
Deployment rollout started:
Synchronization verified:
Authentication errors checked:
Inactive workloads reviewed:
Old secret removed:
Completion time:
Incident or change-management link:

Compromise response runbook

Incident owner:
Detection time:
Affected project:
Affected environment:
Exposure source:
Potentially affected systems:
Replacement key created:
Replacement deployed:
Compromised key invalidated:
Synchronization verified:
Repository or artifact cleanup completed:
Logs reviewed:
Security team notified:
Follow-up actions:
Retrospective link:

API key checklist

Common misconceptions

"An API key is used every time a flag is evaluated."

False. Evaluation uses the local in-memory snapshot.

"A private Git repository is a safe secret store."

False. Repository access, clones, logs, and CI systems expand the exposure surface.

"Production and Development can share one key."

False. Each environment should have isolated credentials.

"Removing a leaked key from source code makes it safe again."

False. The credential must be regenerated so the previous value is invalidated.

"Updating a secret manager automatically updates every running process."

Not necessarily. The deployment platform may require reload, restart, or rollout.

"If flags still evaluate, the new key must be working."

False. The SDK may be reading an existing snapshot while synchronization is failing.

"A mobile application can securely hide an embedded key."

False. Distributed binaries should be treated as inspectable.

"Feature flags can enforce authorization."

False. Authorization must remain in the application’s trusted security layer.

"Regenerating a key always stops the application immediately."

False. Local evaluation may continue from the current snapshot, but future synchronization fails until the new key is deployed.

"One successful instance proves rotation is complete."

False. Every consuming deployment must be verified.

"SOASAP keeps the old and new keys valid during rotation."

False. Regenerating an environment key permanently invalidates the previous key.

Relationship to other SOASAP concepts

Related documentation

• Security — production credential and secret-handling practices
• Environments — environment scope and configuration boundaries
• SDK Installation — choose and install the right SDK
• Local Evaluation — in-memory evaluation without per-read authentication
• Real-Time Synchronization — authenticated SSE configuration delivery
• Persistent Cache — snapshot restoration when sync cannot reauthenticate
• Offline Operation — evaluation without successful synchronization
• High Availability — availability vs configuration freshness
• Outages — incident behavior during sync loss
• Cache Strategy — cache isolation across environments
• Invalid API Key — diagnosing rejected credentials
• SSE Disconnected — synchronization interruptions
• Cache Not Restored — restart behavior without a valid snapshot
• .NET SDK
• Node.js SDK
• Python SDK
• React SDK
• Angular SDK
• React Native SDK
• Kotlin SDK