> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/api/identity-manager-api/invitations.md).

# Invitations

## List operator invitations

> Returns a paginated list of the pending and expired invitations to the given Tenant's operator organization. Accepted invitations are removed by Keycloak and therefore never appear.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Identity Manager Documentation","version":"0.1.2"},"tags":[{"name":"Invitations","description":""}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"GetInvitationsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GetInvitationsResponseItem"}},"pagination":{"$ref":"#/components/schemas/PaginationData"}},"required":["items","pagination"]},"GetInvitationsResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"Invitation unique ID"},"email":{"type":"string","description":"Email address the invitation was sent to"},"firstName":{"type":"string","description":"Given name captured when the invitation was sent"},"lastName":{"type":"string","description":"Family name captured when the invitation was sent"},"status":{"type":"string","description":"Whether the invitation is still usable or has passed its expiry","enum":["PENDING","EXPIRED"]},"sentAt":{"type":"string","description":"Moment the invitation email was last sent, as an ISO 8601 timestamp"},"expiresAt":{"type":"string","description":"Moment the invitation link stops working, as an ISO 8601 timestamp"}},"required":["id","email","status","sentAt","expiresAt"]},"PaginationData":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"}},"required":["page","limit"]}}},"paths":{"/api/v1/invitations":{"get":{"description":"Returns a paginated list of the pending and expired invitations to the given Tenant's operator organization. Accepted invitations are removed by Keycloak and therefore never appear.","operationId":"InvitationsController_list_api/v1","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"type":"number"}},{"name":"tenantId","required":true,"in":"query","description":"Tenant unique ID","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Returns only the invitations in this state","schema":{"type":"string","enum":["PENDING","EXPIRED"]}},{"name":"invitee","required":false,"in":"query","description":"Free-text filter matched against email, first name and last name","schema":{"type":"string"}}],"responses":{"200":{"description":"When the organization invitations are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInvitationsResponse"}}}},"401":{"description":"When the agents-realm token is missing or invalid, or belongs to a client other than the Service Provider."},"404":{"description":"- When the caller is a Tenant rather than the Service Provider.\n- When no tenant is registered under the given tenantId, or its operator organization does not exist in the realm."},"500":{"description":"When the Keycloak Admin API request fails, including invitation email delivery."}},"summary":"List operator invitations","tags":["Invitations"]}}}}
```

## Invite a Tenant operator

> Sends a Keycloak organization invitation to the given address, for the given Tenant's operator organization. The emailed link lands on the registration page with the address bound to the invitation, so completing registration creates the operator account and its organization membership in one step — which is what puts the Tenant id in their token. The operator then claims their Tenant separately, via POST /tenants/me/client.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Identity Manager Documentation","version":"0.1.2"},"tags":[{"name":"Invitations","description":""}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateInvitationRequest":{"type":"object","properties":{"tenantId":{"type":"string","description":"Tenant unique ID"},"email":{"type":"string","description":"Email address the organization invitation is sent to"},"firstName":{"type":"string","description":"Given name used to personalise the invitation email"},"lastName":{"type":"string","description":"Family name used to personalise the invitation email"}},"required":["tenantId","email"]}}},"paths":{"/api/v1/invitations":{"post":{"description":"Sends a Keycloak organization invitation to the given address, for the given Tenant's operator organization. The emailed link lands on the registration page with the address bound to the invitation, so completing registration creates the operator account and its organization membership in one step — which is what puts the Tenant id in their token. The operator then claims their Tenant separately, via POST /tenants/me/client.","operationId":"InvitationsController_create_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitationRequest"}}}},"responses":{"204":{"description":"When the invitation email has been sent."},"400":{"description":"When Keycloak refuses the address, or the organization is disabled."},"401":{"description":"When the agents-realm token is missing or invalid, or belongs to a client other than the Service Provider."},"404":{"description":"- When the caller is a Tenant rather than the Service Provider.\n- When no tenant is registered under the given tenantId, or its operator organization does not exist in the realm."},"409":{"description":"When the address already has a pending invitation or is already a member."},"500":{"description":"When the Keycloak Admin API request fails, including invitation email delivery."}},"summary":"Invite a Tenant operator","tags":["Invitations"]}}}}
```

## Resend an invitation

> Sends a fresh invitation email with a new expiry. Keycloak revokes the previous invitation and issues a new one, so the invitation id changes and the list must be refetched.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Identity Manager Documentation","version":"0.1.2"},"tags":[{"name":"Invitations","description":""}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}}},"paths":{"/api/v1/invitations/{id}/resend":{"post":{"description":"Sends a fresh invitation email with a new expiry. Keycloak revokes the previous invitation and issues a new one, so the invitation id changes and the list must be refetched.","operationId":"InvitationsController_resend_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Invitation unique ID","schema":{"type":"string"}},{"name":"tenantId","required":true,"in":"query","description":"Tenant unique ID","schema":{"type":"string"}}],"responses":{"204":{"description":"When a fresh invitation email has been sent."},"401":{"description":"When the agents-realm token is missing or invalid, or belongs to a client other than the Service Provider."},"404":{"description":"- When the caller is a Tenant rather than the Service Provider.\n- When the invitation does not exist or belongs to another organization, or the given tenantId names no organization in the realm."},"409":{"description":"When the address already has a pending invitation or is already a member."},"500":{"description":"When the Keycloak Admin API request fails, including invitation email delivery."}},"summary":"Resend an invitation","tags":["Invitations"]}}}}
```

## Revoke an invitation

> Deletes a pending invitation and invalidates the link that was emailed with it.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Identity Manager Documentation","version":"0.1.2"},"tags":[{"name":"Invitations","description":""}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}}},"paths":{"/api/v1/invitations/{id}":{"delete":{"description":"Deletes a pending invitation and invalidates the link that was emailed with it.","operationId":"InvitationsController_revoke_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Invitation unique ID","schema":{"type":"string"}},{"name":"tenantId","required":true,"in":"query","description":"Tenant unique ID","schema":{"type":"string"}}],"responses":{"204":{"description":"When the invitation has been revoked and its link invalidated."},"401":{"description":"When the agents-realm token is missing or invalid, or belongs to a client other than the Service Provider."},"404":{"description":"- When the caller is a Tenant rather than the Service Provider.\n- When the invitation does not exist or belongs to another organization, or the given tenantId names no organization in the realm."},"500":{"description":"When the Keycloak Admin API request fails, including invitation email delivery."}},"summary":"Revoke an invitation","tags":["Invitations"]}}}}
```


---

# 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://docs.toolkit.equs.ai/api/identity-manager-api/invitations.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.