# Your first call

Five minutes from a key to your first page of records. Every request and answer below is a real example, copied as the reference pages show it. Every id in the examples is made up and resolves nowhere.

## The shape of a call

Every call is a POST to `https://api.almondtill.com/` with a JSON body of three parts: `query` — the operation, written in GraphQL; `variables` — its arguments; and `extensions` — the envelope. There is one address for all 1018 operations, and one answer shape: `data` holds the result under the operation's name, `errors` appears only when something was refused, and `extensions.at` is the envelope that comes back on every answer ([Versions and the envelope](/guides/versions-and-the-envelope/)).

## Step 1 — mint a key

An owner of your organization group mints an API key in the office, under API keys, choosing what the key may do. The secret is shown once; copy it into your integration's secret store then and there. The whole life of a key is in [Authentication and key hygiene](/guides/authentication-and-key-hygiene/).

## Step 2 — exchange the secret for a session

The key's secret never rides on your calls. Exchange it once for a session token with [exchangeApiKey](/reference/open-doors/exchangeApiKey/) — no token yet, the secret is the credential — naming the organization the session will act in:

### Example request

```graphql
mutation ExampleExchangeApiKey($input: ExchangeApiKeyInput!) {
  exchangeApiKey(input: $input) {
    token
    expiresAt
  }
}
```

Variables:

```json
{
  "input": {
    "secret": "<your key secret>",
    "orgId": "01900000-0000-7000-8000-b0cf4f3c0000"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

### Example response

```json
{
  "data": {
    "exchangeApiKey": {
      "token": "<your session token>",
      "expiresAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```


The token lasts 24 hours. Send it on every call after this one as an `authorization: Bearer <your session token>` header.

## Step 3 — read your first page

Ask for a small page of one listing — your brands, say — with the token in the header:

Send it with the token as `authorization: Bearer <your session token>`:

```json
{
  "query": "query FirstBrands($limit: Int) { brands(limit: $limit) { items { sysId caption status } nextToken } }",
  "variables": {
    "limit": 3
  }
}
```

The answer is a page:

```json
{
  "data": {
    "brands": {
      "items": [
        {
          "sysId": "BR-EXMP-0000-000F",
          "caption": "Blue jeans",
          "status": "active"
        }
      ],
      "nextToken": null
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

`items` holds the records; `nextToken` is `null` because this small page is complete — a longer listing answers a cursor there, and [Paging and the cursor grammar](/guides/paging-and-the-cursor-grammar/) walks it.

## What you have now

A working session and a page of your own records. From here: every operation has a page in the [reference](/reference/) with a request and a response to copy; a change names its version in the envelope ([Versions and the envelope](/guides/versions-and-the-envelope/)); a refusal is a structured error with a retry verdict ([Errors and retries](/guides/errors-and-retries/)); and the [use cases](/use-cases/) walk whole jobs step by step, each step with its operations.