> For the complete documentation index, see [llms.txt](https://docs.zenlytic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenlytic.com/developers/readme.md). # Overview Use the Zenlytic API to manage your organization and workspaces programmatically. Endpoints are organized into two scopes — organization-wide and single-workspace — each requiring a differently-scoped personal access token; see [Authentication](#authentication) below, and the API Reference for the full endpoint breakdown. ## Authentication Personal access tokens (PATs) authenticate API requests to Zenlytic on behalf of your user account, without requiring an interactive login for each request. Use a PAT for scripts, CI pipelines, BI tool integrations, and other automated access to the Zenlytic API. ### Creating a Personal Access Token {% hint style="info" %} Creating, viewing, and revoking personal access tokens requires the [Admin or Organization Admin role](https://github.com/Zenlytic/zenlytic-docs/tree/main/docs/zenlytic-ui/user_roles.md) in the workspace you're doing it from. If you don't have this role, the **API Access** item won't appear in your user menu, and the Personal Access Tokens page isn't reachable even by direct link. {% endhint %} A token's scope is fixed at creation time, based on your role in the workspace you're creating it from — it has nothing to do with which endpoint you later call. If you hold the Org Admin role there, the token you create is org-wide; otherwise it's scoped to that workspace only. Two tokens can look identical — same format, same header — while one reaches your whole organization and the other reaches a single workspace, so confirm your role before creating a token, or call `GET /me` afterward to check what you actually got. 1. Click your user avatar/name in the bottom-left corner of the navigation bar. 2. Select **API Access** from the user menu. ![](https://354234119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeLZgzxMyhrn1Qfj191Xe%2Fuploads%2Fgit-blob-4da36e9022b04626bf48c1c46232efee4ed26a47%2Fpat-user-menu.png?alt=media) 3. On the Personal Access Tokens page, click **Create Token**. 4. Enter a descriptive name for the token so you can identify its purpose later. ![](https://354234119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeLZgzxMyhrn1Qfj191Xe%2Fuploads%2Fgit-blob-3efd26896a49e597f51bb0331c6af5f9bec0bd67%2Fpat-create-token-modal.png?alt=media) Select "All Workspaces" from the dropdown if you're an org admin to gain access to the org admin APIs. ![](https://354234119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeLZgzxMyhrn1Qfj191Xe%2Fuploads%2Fgit-blob-f9f453a75afda79c0d01305a7981b3c3e8a51d13%2Fpat-create-token-modal-select-workspace-scope.png?alt=media) 5. Click **Create**. Your new token displays once. 6. Copy the token immediately and store it somewhere secure, such as a secrets manager or password manager. Zenlytic does not store the raw token, and you cannot view it again after closing this dialog. ### Discovering Your Token's Scope A PAT's reach — a single workspace or your entire organization — isn't visible from the token itself or from anything in your request. Before building against a new token, call `GET /me` to see what it can actually do: ```bash curl -H "Authorization: Bearer " \ https://api-external.zenlytic.com/api/v2/me ``` It returns the calling token's organization and the workspaces it can see — one workspace for an admin-scoped token, or every workspace in the organization for an org admin token. `/me` only accepts PAT authentication; it isn't reachable using an interactive session login. | Scope | Access | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Admin** | Tied to the workspace that was active when you created the token. Has the same permissions as your user account within that workspace. | | **Org admin** | Org-wide. Authenticates requests across every workspace in your organization; the organization is derived from the token, never from anything you pass in. Since org admins also have admin permissions in every workspace, an org admin token can additionally call every admin-scoped endpoint too. | ### Managing Existing Tokens The Personal Access Tokens page lists all tokens associated with your account, including their name and creation date. Tokens are identified only by name and metadata. The raw token value is never shown again after creation, so keep your own record of which token is used where. ### Revoking a Token 1. Go to **API Access** 2. Find the token to revoke in the list and click the delete (trash) icon. 3. Confirm the deletion in the dialog. This action is immediate and permanent. Once deleted: * The token can no longer authenticate; future API requests using it are rejected. * You cannot view or restore the token. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.zenlytic.com/developers/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.