raw .md

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

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.

{
  "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

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:

{
  "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

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:

{
  "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

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:

{
  "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

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