Authentication

The Interactions API uses HTTP Basic Authentication to secure all endpoints.

How to Authenticate

1. Obtain your API key from DDx API as explained here, and copy its API key secret. Treat these credentials as sensitive information. Do not share or expose them in public repositories or client-side code.
2. Include an Authorization header in every request to the Interactions API:

Authorization: Basic <credentials>

Example

The value you authenticate with is the API key secret, and it goes in the password position of the Basic credentials. It is not the bare secret: it is the API key ID, a literal ., then the secret. The Admin API's Get Interactions API Key Secret endpoint returns it in that form as apiKeySecret, so use the value verbatim.

If your org name is my_org and your API key secret is 42.bVAynbc234qafdsg2345sdfrfF, encode my_org:42.bVAynbc234qafdsg2345sdfrfF in Base64 to get bXlfb3JnOjQyLmJWQXluYmMyMzRxYWZkc2cyMzQ1c2RmcmZG. Use that value in your Authorization header.

Authorization: Basic bXlfb3JnOjQyLmJWQXluYmMyMzRxYWZkc2cyMzQ1c2RmcmZG

Testing your API Key

The /auth/me endpoint allows you to verify that your API key secret is valid and active. It returns the key's ID as publicKeyId, which is the same number that prefixes the secret. Use this endpoint to test or validate your API credentials before making other requests. No request body is required.

More documentation on this endpoint is available here.

Example

1. Send a GET request to /auth/me with your Basic Authentication header.

GET /v1/auth/me HTTP/1.1
Host: api.movementinfrastructure.org
Authorization: Basic <Base64-encoded-credentials>

curl https://api.movementinfrastructure.org/v1/auth/me -H "Authorization: Basic <Base64-encoded-credentials>"

2. Check the response:
   1. A 200 OK response confirms your credentials are valid.
   2. A 401 Unauthorized response means your credentials are missing, malformed, use a scheme other than Basic, or are invalid.

Notes

• All API requests must use HTTPS to protect credentials and data in transit.
• All API requests must include the Authorization header.
• If authentication fails, the API returns a 401 Unauthorized response. A missing Authorization header, a malformed one, or a scheme other than Basic all return 401 as well.
• Never share your API key secret.
• For more details, see the HTTP Basic Authentication specification.