Authentication and Authorization Guidelines

Use these guidelines when operating Auth Service or integrating with platform authentication.

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

• 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

• 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

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.

Related

• RBAC and Membership — what each role grants, for least-privilege assignment
• API Keys and Service Accounts — choosing between user API keys and service accounts
• Token Exchange and Refresh Tokens — refresh-token rotation and its reuse window
• Identity Providers — what each provider mode supports before you change it
• Member Management — reviewing and changing membership in Guardian