> For the complete documentation index, see [llms.txt](https://help.allwage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.allwage.com/fundamentals/external-api-tokens.md).

# External API Tokens

Create API keys so your own systems, or a partner's, can read data from AllWage or send clock records to it.

The AllWage External API lets another system connect to AllWage directly. For example, your internal reporting tool can read employees and daily attendance, or a partner's clocking system can send clock records in.

Every system that connects needs its own **API key**. You create and manage these keys on the **External API tokens** page.

**What this page covers:**

* Who can create API tokens
* Creating a token and copying its key
* Choosing scopes: what each token can access
* Changing, disabling and re-enabling a token
* What to do if a key is lost

**Who this is for:**

Owners, and the developers or partners they work with to connect systems to AllWage.

## Who Can Manage API Tokens

Only **Owners** can open the External API tokens page. No other preset can give this access, including custom presets. See [Designing and Troubleshooting Access](https://help.allwage.com/fundamentals/users-and-employees/user-permissions/designing-and-troubleshooting-access.md#owners) for how someone becomes an Owner.

If you aren't an Owner, ask one of your Owners to create the token for you.

{% hint style="info" %}
A token belongs to the profile it was created in, and gives access to that profile's data. If you have more than one profile, create a separate token in each.
{% endhint %}

## Create a Token

1. Go to **Settings > External API tokens**.
2. Click **Create token**.
3. Under **Token details**, give the token a **Name** that says which system or partner will use it, for example "Internal reporting".
4. Click **Scopes** and select what the token can access. Choose only what the system needs. Click **Use scopes**.
5. Optionally, open **Advanced**:
   * **Partner code** — a reference for the partner using the token, for example `PAYROLL-PARTNER`. It's for your records and doesn't give extra access.
   * **Expiry date** — the token stops working at the end of this day. Leave it empty for a token that doesn't expire.
6. Click **Create token**.

## Copy the API Key

When the token is created, AllWage shows its **API key** once.

1. Click **Copy API key**.
2. Store it somewhere secure, such as your password manager, or pass it straight to the developer who's setting up the connection.
3. Click **Close**.

{% hint style="danger" %}
**The key is only shown once.** After you close the panel, nobody can see it again, including AllWage support. Treat the key like a password: don't send it in a group chat or paste it into a shared document.
{% endhint %}

If the copy button doesn't work, select the key and copy it by hand before you close the panel.

## Choosing Scopes

Scopes decide what a token can do. A token can only read or change the things you select.

| Scope                                             | What it allows                                                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **View daily attendance** (`attendance:read`)     | View daily attendance status, scheduled shifts, clock times, leave and worked hours for employees in this profile. |
| **View employee clock records** (`clock:read`)    | View raw clock records, timestamps and activities for employees in this profile.                                   |
| **Import employee clock records** (`clock:write`) | Create employee clock records in this profile.                                                                     |
| **View employees** (`employee:read`)              | View employees and the details needed to match them in another system.                                             |

The scope names in brackets are what developers see in the [API documentation](https://developers.allwage.com/).

{% hint style="warning" %}
**Import employee clock records** is the only scope that adds data to AllWage. Only select it for a clocking system you trust to send clocks in. A reporting tool only needs the **View** scopes.
{% endhint %}

## Give the Key to Your Developer

Developers can find the full technical reference at [developers.allwage.com](https://developers.allwage.com/). It lists every available endpoint, explains how to send the key with each request, and shows what data each request returns. You can also open it from the **API documentation** button at the top of the External API tokens page.

Each token can make up to **60 requests per minute**. If a system goes over this, AllWage asks it to wait and try again.

## Manage Your Tokens

The External API tokens page lists every token in your profile. For each token you can see its name, the start of its key (so you can tell tokens apart), its scopes, its status, when it expires and when it was last used.

A token has one of three statuses:

* **Active** — the token works.
* **Disabled** — an Owner switched it off. Systems using it can't connect.
* **Expired** — the expiry date has passed. Systems using it can't connect.

**Last used** is a quick way to check whether a connection is working, or whether an old token is still in use before you disable it.

### Change a Token

Click a token's row, or click **⋯** and choose **Edit**. You can change its name, scopes, partner code and expiry date, then click **Save**. Changes apply to the existing key, so the connected system doesn't need a new one.

### Disable a Token

Click **⋯** on the token's row and choose **Disable**, then **Disable token** to confirm.

The system using the token stops working immediately. Disable a token when a connection is no longer needed, when you stop working with a partner, or if you think the key has been shared with someone who shouldn't have it.

### Enable a Token Again

Click **⋯** on a disabled token's row and choose **Enable**, then **Enable token**. The same key works again, so nothing needs to change on the connected system.

To bring back an **expired** token, edit it and choose a later expiry date first.

## Lost a Key?

A key can't be shown again. If it's lost:

1. Create a new token with the same scopes and give the new key to your developer.
2. Once the connection works with the new key, disable the old token.

If you think a key has been seen by someone who shouldn't have it, disable that token straight away, then create a new one.

## Frequently Asked Questions

**Can I limit a token to one team?** No. A token can see the whole profile it was created in. Choose scopes carefully, and only share the key with systems that need it.

**Can I delete a token?** No. Disable it instead. A disabled token can't be used, and the record of it stays in your list.

**Can the API change or delete employee data?** No. Apart from importing clock records, the API only reads data.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.allwage.com/fundamentals/external-api-tokens.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
