# Security

This page covers what you need to do to keep your integration secure. It does
not describe how the service is built.

## Use HTTPS

Always call GAUTH over HTTPS. Never send a credential over plain HTTP.

## Store credentials properly

- Keep `gtk_`, `gsk_` and `gak_` keys in a secret manager or an encrypted store.
- Never commit a key to source control.
- Never log a key or a token.
- Never ship a management key in client-side code. Management keys belong on
  your server.

## Use one key per service

Issue a separate labelled key for each service, device or environment. If one
is compromised, revoke it without breaking the others.

## Rotate on a schedule

Rotate keys on a regular schedule and immediately after any suspected exposure.
Rotation is immediate: anything still using an old key stops working.

## Keep tokens short-lived

Treat `expires_in` as authoritative. Request a new token when one expires.
Do not cache a token past its expiry.

## Validate the OAuth state

Generate a random `state` value for every authorization request and check it
when the user returns. Reject a callback whose `state` does not match.

## Use the narrowest scope

Request only the scope your app needs. A client token can manage that client's
resources. An app user token can read and update that user's profile.

## Revoke what you no longer need

Revoke a key or session as soon as it is no longer needed. Revocation is
immediate.

## Report a problem

If you find a vulnerability, contact the operator of this GAUTH deployment
through the same channel you use for support. Do not open a public issue with
exploit details.