# 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.