Getting Started
Authentication
All DeepaData API requests require authentication via API key. Keys are scoped to specific operations and can be managed from the console.
API Key Format
DeepaData API keys follow the format dda_live_*. Each key is tied to your organization and can be configured with specific scopes.
Example: dda_live_sk_7f3a2b1c9e8d...
Authentication Methods
Include your API key in requests using one of these methods:
Authorization Header
Pass the API key as a Bearer token in the Authorization header.
curl -X POST https://www.deepadata.com/api/v1/extract \
-H "Authorization: Bearer dda_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "..."}'X-API-Key Header
Alternatively, pass the key directly in the X-API-Key header.
curl -X POST https://www.deepadata.com/api/v1/extract \
-H "X-API-Key: dda_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "..."}'API Key Scopes
Each API key can be configured with specific scopes that control which endpoints the key can access. This follows the principle of least privilege.
| Scope | Endpoints | Description |
|---|---|---|
extract | /v1/extract, /v1/observe, /v1/batch/* | Create extractions and observations |
validate | /v1/validate | Validate artifacts against schema |
issue | /v1/issue | Seal artifacts into .ddna envelopes |
verify | /v1/verify, /v1/certificate/:id | Verify envelopes and retrieve certificates |
vitapass | /v1/vitapass/* | Manage consent scopes and presentations |
Tip: Create separate keys for different environments (development, staging, production) and services. Rotate keys regularly.
Error Responses
Authentication errors return standard HTTP status codes with descriptive messages.
401Unauthorized
Missing or invalid API key. Check that the key is correctly formatted and active.
403Forbidden
API key does not have the required scope for this endpoint.
429Rate Limited
Too many requests. Check the Retry-After header for when to retry.
Rate Limits
Rate limits vary by plan tier. Exceeding limits returns HTTP 429 with aRetry-Afterheader.
| Tier | Rate Limit | Monthly Quota |
|---|---|---|
| Free | 10 requests / minute | 1,000 calls |
| Starter | 30 requests / minute | 10,000 calls |
| Pro | 60 requests / minute | 50,000 calls |
| Enterprise | Custom | Unlimited |
Security Best Practices
Never expose keys in client-side code
API keys should only be used server-side. Never include them in browser JavaScript, mobile apps, or public repositories.
Use environment variables
Store keys in environment variables (e.g., DEEPADATA_API_KEY) rather than hardcoding them in source code.
Rotate keys regularly
Create new keys periodically and deprecate old ones. Use separate keys for each environment and service.
Use minimal scopes
Only enable the scopes each key needs. A key that only extracts doesn't need issue or verify permissions.
If your key is compromised
Immediately revoke the key from the console and create a new one. Review your API logs for unauthorized access.