# GatePass API
Source: https://docs.infraista.com/en/networking/gatepass/gatepass-api



The GatePass API lets you invite and manage GatePass people from your own platform (HR system, identity
provider, internal admin).

## Create a key [#create-a-key]

Select **Create a GatePass key** on **GatePass › API**, or go to **Settings › API keys** and choose the
**GatePass only** key type. Pick the organization and the scopes:

| Scope            | Allows                                                    |
| ---------------- | --------------------------------------------------------- |
| `gatepass:read`  | See people and hubs                                       |
| `gatepass:users` | Invite, update, suspend and remove people (includes read) |

A key acts as the person who made it: their GatePass permissions in that organization apply. See
[API keys](/en/account/api-keys).

## Endpoints [#endpoints]

Base URL: `https://api.infraista.com/api/v1/gatepass`

| Request                                          | Does                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `GET /hubs`                                      | Your hubs (ids and names)                                        |
| `GET /users`                                     | People, filtered by status, email, externalId or hub             |
| `GET /users/{id}`                                | One person; add `?by=externalId` to look up by your own id       |
| `POST /users`                                    | Invite someone: email, name, your externalId, hubs by id or name |
| `PATCH /users/{id}`                              | Change name, role, hubs or externalId                            |
| `POST /users/{id}/suspend`, `/resume`, `/resend` | Suspend (signs them out everywhere), resume, resend the invite   |
| `DELETE /users/{id}`                             | Remove them from GatePass                                        |

## Examples [#examples]

Invite someone:

```bash
curl -X POST https://api.infraista.com/api/v1/gatepass/users \
  -H "Authorization: Bearer <GatePass key>" -H "Content-Type: application/json" \
  -d '{"email": "nour@example.com", "name": "Nour Adel", "externalId": "hr-1042", "hubs": ["Studio Ops"]}'
```

Offboard someone by your own id:

```bash
curl -X POST "https://api.infraista.com/api/v1/gatepass/users/hr-1042/suspend?by=externalId" \
  -H "Authorization: Bearer <GatePass key>"
```

## Good to know [#good-to-know]

* Inviting an email that already has GatePass returns that person (`200`, `"created": false`), so
  retries are safe.
* People still set their own password and two-factor from the invite email; the API never handles
  passwords.
* Seats are billed when someone becomes active, not when they're invited.

## Related [#related]

* [Manage GatePass users](/en/networking/gatepass/manage-users)