Concepts
Two kinds of account
GAUTH separates two kinds of account.
- A client account owns applications. You use it to register apps, manage their users and issue credentials.
- An app user belongs to one application, or to one app family when sub-apps are used. App users sign in through your app.
The two account types have separate sign-in policies. Client sign-ins are strictly rate-limited. App user sign-ins are lenient by default and can be tuned per app.
Objects
| object | identifier | notes |
|---|---|---|
| client | cid like c_4m2x9p | owns apps, holds a management key |
| app | app_key like app_1a2b3c4d5e6f7a8b | public identifier, plus a private app_secret |
| sub-app | app_key | an app with parent_app_id set, shares the parent user pool |
| app user | uid like a_9k2m4x | belongs to one app or app family |
| token | cgt_... | short-lived bearer token |
| client key | gtk_... | long-lived management key |
| app secret | gsk_... | long-lived app credential |
| app user key | gak_... | long-lived per-account key |
The uid is your join key
The uid is the stable identifier for an app user. It never changes and it is not a secret. Store it in your own database and key your rows on it.
Do not key your database on a token. Tokens expire and are replaced.
Tokens
A Certified Gump Token is a bearer token. It is short-lived. There are no refresh tokens: when a token expires, run the token request again.
A token carries a scope.
| scope | who | what it can do |
|---|---|---|
client | a client password grant | manage that client's apps and profile |
app profile | an app user password or code grant | read and update that app user's profile |
app | a client_credentials grant | act as the app, no user |
Sub-apps
A sub-app is an app with parent_app_id set. It shares its parent's user pool, so one app user account works across the family. Sub-apps cannot have their own sub-apps. Attach to the root app instead.
Key prefixes
Prefixes make a credential easy to identify in logs and secret scanners.
| prefix | kind | used as |
|---|---|---|
gtk_ | client management key | Authorization: Bearer gtk_... on the management API |
gsk_ | app secret | client_secret in token requests |
gak_ | app user key | Authorization: Bearer gak_... on the public API |
cgt_ | session token | Authorization: Bearer cgt_... on the public API |
Status values
Clients, apps and app users are either active or disabled. A disabled object cannot authenticate. Disabling a client, app or app user revokes the relevant sessions.
Timestamps
All timestamps are Unix seconds in UTC. The API returns integers, not strings.