# Quickstart

This walks through the whole flow in about five minutes: create a client
account, register an app, create an app user, exchange credentials for a token,
and call the identity endpoint.

## 0. Set your base URLs

```bash
export GAUTH="https://auth.gumpworks.com"
export API="$GAUTH/api/v1"
export MANAGE="$API/manage"
```

## 1. Create a client account

Sign up at `https://auth.gumpworks.com/signup`, or ask your administrator to
create the account. The response includes a management key.

```json
{
  "cid": "c_4m2x9p",
  "username": "acme",
  "api_key": "gtk_...",
  "warning": "Store api_key now; it is not recoverable."
}
```

Store `api_key`. It authenticates your management API calls and is shown once.

## 2. Register an app

```bash
curl -sS -X POST "$MANAGE/apps" \
  -H "Authorization: Bearer gtk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"acme-app","redirect_uris":["https://acme.example/cb"]}'
```

Response:

```json
{
  "id": 1,
  "app_key": "app_1a2b3c4d5e6f7a8b",
  "name": "acme-app",
  "status": "active",
  "app_secret": "gsk_...",
  "warning": "Store app_secret now; it is not recoverable."
}
```

Store `app_secret`. It is shown once.

## 3. Create an app user

```bash
curl -sS -X POST "$MANAGE/apps/1/users" \
  -H "Authorization: Bearer gtk_..." \
  -H "Content-Type: application/json" \
  -d '{"app_username":"alice","password":"a-long-password"}'
```

Response:

```json
{
  "id": 1,
  "uid": "a_9k2m4x",
  "app_id": 1,
  "app_username": "alice",
  "status": "active",
  "api_key": "gak_...",
  "warning": "Store api_key now; it is not recoverable."
}
```

Store the `uid`. It is the stable join key for your own database.

## 4. Get a token

```bash
curl -sS -X POST "$API/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "app_1a2b3c4d5e6f7a8b",
    "client_secret": "gsk_...",
    "username": "alice",
    "password": "a-long-password"
  }'
```

Response:

```json
{
  "access_token": "cgt_...",
  "token_type": "Bearer",
  "expires_in": 43200,
  "scope": "app profile",
  "uid": "a_9k2m4x",
  "app": "app_1a2b3c4d5e6f7a8b",
  "app_username": "alice",
  "client": "c_4m2x9p"
}
```

## 5. Call the API

```bash
curl -sS "$API/userinfo" -H "Authorization: Bearer cgt_..."
```

## 6. Use the uid as your join key

Store `uid` in your own database. It never changes. Do not key your rows on a
token, because tokens expire and are replaced.

## Next

- [Authentication](authentication.md) - every grant type and the identity endpoints.
- [Management API](management.md) - the full management surface.
- [Errors and limits](errors.md) - what to do when a call fails.