Authentication and security

The X-Api-Key header

Every call is authenticated with an API key in the X-Api-Key header:

curl "https://sandbox-api.saludenruta.es/api/integrations/v1/catalog" \
  -H "X-Api-Key: srd_test_3f9a1c2b_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

A key has three parts separated by underscores:

With no header, or with a key that is unknown, revoked, expired or belongs to a deactivated provider, the API always responds the same way: 401 with the type /errors/provider-api/invalid-key. We deliberately don't say why, so as not to give hints to anyone trying out keys.

Salud en Ruta only stores a cryptographic hash (SHA-256) of each key, not the key itself. That's why it is shown only once, when it's created, and we can't recover it if you lose it: a new one has to be generated.

Scopes

Each key has one or more scopes that limit what it can do. Only ask for the ones you need: a key that only reads statuses shouldn't be able to create visits.

A valid key that lacks the scope gets a 403 with the type /errors/provider-api/scope-missing, and the missing scope in the detail ("La clave de API no tiene el ámbito visits:write", or "The API key lacks the visits:write scope" with Accept-Language: en).

Key lifecycle

Keys are created, rotated and revoked by Salud en Ruta from its intranet, at your request. Email us with the key's prefix (never the full key).

• Creation: with a name (which system it's for), its scopes, its rate limit per minute and, optionally, an expiry date. The full key is handed over to you once, through a secure channel.
• Rotation: a new key is generated with the same name, scopes, limit and expiry, and the previous one is revoked at the same moment. Agree the time with us so you can deploy the new key at exactly the same time.
• Revocation: takes effect immediately. No cache keeps a revoked key alive: the very next request gets a 401.
• Expiry: if the key has an expiry date, from that moment on it responds 401 just like a revoked one. Let us know in good time so we can generate the next one.

We record when, and from which IP address, each key was last used, which helps us investigate any unusual activity with you.

Best practices

• Server-side only. The key gives access to your organisation's visits: never put it in a website, a mobile app, a browser script or a repository. If your front end needs data, have it ask your back end, and have your back end call the API.
• In a secrets manager or environment variables, not in code or in version-controlled configuration files. One key per environment: srd_test_… in development and staging, srd_live_… only in production.
• Don't log it. Make sure your logs, traces and monitoring tools don't store the X-Api-Key header (many store every header by default).
• Least privilege: only the scopes you need, as explained above.
• Rotate periodically and when your team changes.

Transport and IP addresses

• Always call over HTTPS, using the base URLs in environments. Never send the key over unencrypted HTTP.
• Your HTTP client must verify the server certificate. Don't disable verification, not even for testing.
• Calls to the API can come from any IP address: security relies on the key, not on the origin. If your organisation has to go through a proxy or restricts outbound destinations, allow api.saludenruta.es and sandbox-api.saludenruta.es.
• The webhooks we send you come from Salud en Ruta's servers. We don't recommend filtering by IP address (they may change without notice): the signature is what guarantees a delivery comes from us.

If a key leaks

If you suspect a key has been exposed (it was pushed to a repository, it showed up in a shared log, someone who has left had it):

1. Email us immediately at info@saludenruta.es with the subject "Clave comprometida" (compromised key) and the key's prefix. If it's urgent, also call the dispatch centre (+34 611 673 280).
2. We revoke it straight away and give you a new one (rotation). Deploy the new key in your system.
3. Review the usage together: we'll tell you when and from which IP address the key was last used, so you can check for calls you don't recognise.
4. Remove the key from wherever it leaked (git history included) and find out how it got there.

A webhook secret is handled the same way: if it leaks, ask us to rotate it.