> For the complete documentation index, see [llms.txt](https://docs.blerify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blerify.com/introduction-to-issuance/reference/api-access-and-scopes.md).

# API Access & Scopes

Before your backend can issue anything, two things have to line up: it has to authenticate as a service account, and that account has to be authorized for the specific project it's acting on. This page covers both — how access is granted, and what each scope lets you do once it is. For the endpoint-by-endpoint contracts, see the [API Reference](https://dev.blerify.com/#01cf28b2-23f9-472d-a822-ab8cc0ce0114).

***

## Prerequisites

* A Blerify organization and at least one project
* A service account provisioned by your Blerify account manager
* Your service account credentials JSON file

***

## Authenticating

The Issuance API authenticates your service account via OAuth 2.0 `client_credentials` with `private_key_jwt` -- there is no client secret. See [Authentication](/introduction/authentication.md) for the complete token exchange walkthrough, including the credentials file fields and the JWT assertion structure.

Send the resulting bearer token on every request:

```http
Authorization: Bearer <access_token>
```

***

## Authorization model

Authenticating gets you a valid token; it doesn't get you access. Blerify scopes service accounts in two layers, and **both have to be true** for a request to succeed:

* **Role** — holding `credentials.api` grants access to the issuance API surface in general.
* **Group membership** — belonging to the group tied to a project scopes that access to *that* project.

This is why a perfectly valid token can still be refused with a `403`. If you hold the role but haven't been added to the project's group, the API returns `403`. That's the most common cause of a `403` on a token you know is good — ask your Blerify account manager to confirm the service account belongs to the project group.

### Scopes

Once both layers line up, the `credentials.api` role grants the following scopes on the project resource:

| Scope                     | What it allows                          |
| ------------------------- | --------------------------------------- |
| `create_credential_item`  | Issue a new credential                  |
| `read_credential_item`    | Retrieve credential status and metadata |
| `update_credential_item`  | Update a credential's attributes        |
| `delete_credential_item`  | Delete a credential record              |
| `approve_credential_item` | Approve a pending issuance              |
| `hold_credential_item`    | Place a credential on hold              |
| `revoke_credential_item`  | Revoke an issued credential             |
| `resend_credential_item`  | Resend a delivery notification          |

You don't request these individually. Your service account receives all of them the moment it holds the role and belongs to the right project group — the authorization server evaluates them automatically against your token.

***

## Where the endpoints live

This page covers *who* can call the API and *what* they're allowed to do. The [**API Reference**](https://dev.blerify.com/#01cf28b2-23f9-472d-a822-ab8cc0ce0114) covers *what to call* — the full request and response schemas, error codes, and example payloads for every endpoint.

***

## Next steps

[**Portal Roles & Permissions**](/introduction/portal-roles-and-permissions.md) — the human counterpart to this page: who on your team can act in the Portal, as opposed to which service account can call the API.

See also: [Issue a W3C Credential](/introduction-to-issuance/build/issue-a-w3c-credential.md) — the calls these scopes authorize · [Handle Errors](/introduction-to-issuance/build/handle-errors.md) — the `403` and other failures, and how to recover.


---

# 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.blerify.com/introduction-to-issuance/reference/api-access-and-scopes.md?ask=<question>&goal=<endgoal>
```

`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.