Authentication and Authorization Guidelines
Use these guidelines when operating Auth Service or integrating with platform authentication.
Access
Section titled “Access”- Assign the least role that lets a user complete their work.
- Prefer project roles for project work.
- Reserve Organization Owner for administrators who manage the platform across projects.
- Review membership when users change teams or responsibilities.
Tokens and Keys
Section titled “Tokens and Keys”- Treat API keys, service-account credentials, and refresh tokens as secrets.
- Store secrets in approved secret management systems.
- Rotate credentials on a regular schedule and after suspected exposure.
- Revoke credentials that are no longer needed.
- Do not paste tokens into tickets, chat, screenshots, or product documentation.
Integrations
Section titled “Integrations”- Use user API keys for customer-managed integrations that need machine access.
- Use service accounts for trusted platform services.
- Validate access in a non-production environment before connecting production systems.
- Keep integration ownership clear so credential rotation does not break platform workflows.
Provider Changes
Section titled “Provider Changes”Changing identity-provider mode can affect sign-in, token validation, membership sync, and token exchange. Plan provider changes as operational changes, not as routine user administration.