Credentials

A Source credential lets a sender send logs as a Source. It is an ID and a secret. Issuing and rotating them happens on the Source's page in the app, and only an owner of the Team can do it.

What a credential is

• The ID is not secret. It is how the gateway knows which credential is being used.

• The secret starts with obs_sk_, followed by random characters. Puck stores only a hash of it, so it can't be shown again.

• Senders use them as HTTP basic auth: the ID is the user name, the secret is the password. The app gives you both as two variables named after the Source, for a Source called api:

  Variable	Holds
  OBS_SOURCE_API_CREDENTIAL_ID	the credential ID
  OBS_SOURCE_API_SECRET	the secret

Every snippet in these docs reads the credential from those variables, and never contains it.

Issuing a credential

Creating a Source issues its first credential. To issue a second, open the Source's page and choose Issue second credential. If the Source has no active credential, the button is Issue credential.

The secret is shown once, in a dialog titled "Copy the secret now". Copy both the ID and the secret into your secret store before you close it. If you lose the secret, you can't get it back: issue a new credential and revoke the lost one.

A new credential works within about a minute, once the gateway has reloaded its credentials.

Rotating a credential

A Source has at most two active credentials, so one can replace the other without a gap. To rotate:

1. Choose Issue second credential on the Source's page.
2. Deploy it to every Host, SDK configuration or Collector that sends as the Source, and restart them.
3. Watch the old credential on the Source's page. It shows when it was last used. Wait until it shows no use for 15 minutes.
4. Revoke the old credential.

If you revoke a credential while a sender still uses it, the gateway rejects that sender's requests with 401, and it drops those logs: it does not retry them. So Puck asks you to confirm first when the credential was used in the last 15 minutes. It won't revoke a credential at all while no other credential of the Source has ever been used, unless you switch the Source off on purpose by typing its slug.

Revoking a leaked secret

If a secret leaked, revoke it straight away and accept that senders using it are rejected. Issue a new credential, and deploy it.

A Source with no credential

A Source with no active credential is switched off: the gateway rejects everything sent to it. Issue a credential to switch it on again.