API Access

Scripts and integrations call the GoChain API with one of two credentials: an organization access key or a personal access token. This page explains what each one reaches and how to create, use and revoke it.

Choosing a Credential

Organization access key Personal access token
Belongs to One GoFabric organization Your user account
Reaches That organization's resources, as its roles allow Everything you can reach, limited by its scope
Header X-Access-Key: <key> Authorization: Bearer glpat_...
Created in Organization Settings → Access Keys Account Settings → Access Tokens
Expiry Optional expiration date 30 days to 1 year
Typical use An application that works with one organization, such as a ledger explorer or a service that reads that organization's peers Automation that works across organizations, business groups and infrastructures, or with lists and containers

Send only one of them per request. A request with both an access key and a personal access token is refused.

Organization Access Keys

An access key belongs to a GoFabric organization. It reaches that organization's resources — its peers, orderers, CA, CC API, GoInitus, certificates and access keys, and the ledger explorer for that organization — within the permissions of the roles you give it. It does not act as any user.

Creating an access key

  1. Open the organization and go to Settings → Access Keys.
  2. Click Create Access Key.
  3. Enter a Name and, optionally, a Description and an Expiration date.
  4. Click Add Role and choose the roles the key needs. A key cannot have the Owner role.
  5. Save. Copy the key from the Save Access Key window: it is not stored and will not be shown again.

The Access Keys table lists each key's name, hash and expiration, with actions to edit or delete it. Deleting a key revokes it immediately.

Using an access key

Send the key in the X-Access-Key header and name the organization in the org_id query parameter where the route asks for it:

curl -H "X-Access-Key: <ACCESS_KEY>" \
  "https://api.chain.goledger.io/api/gofabric/v1/explorer/chain-info?channel_name=<CHANNEL>&org_id=<ORG_ID>"

The ledger explorer routes (/api/gofabric/v1/explorer/transaction, /block and /chain-info) require read permission on the organization's peers, which the owner, administrator, read-only, peer manager and chaincode manager roles grant.

⚠️ Access keys only reach their organization's resources. Requests with an access key to anything else — your user account, lists across organizations, infrastructures, containers, proposals and votes, or websocket notifications — are refused with 403 access keys only reach their org's resources; use a personal access token for anything else. Use a personal access token for those calls. An invalid or expired key is refused; the API never falls back to a browser session.

Personal Access Tokens

A personal access token lets a script call the API as you. It reaches what you can reach, limited by its scope, except your account itself.

Creating a token

  1. Open your account Settings and select the Access Tokens tab.
  2. Click Create Token.
  3. Enter a Name (up to 100 characters) and, optionally, a Description.
  4. Choose the Permissions:
    • Read-only: GET requests only.
    • Read-write: any request, except account, billing and token management.
  5. Choose the Expiration: 30, 60, 90 (default), 180 days or 1 year.
  6. Click create. Copy the token from the Save Your Token window: it is not stored and will not be shown again.

Tokens can only be created, listed and revoked from a signed-in session in the web app; a token cannot manage tokens. The Access Tokens table shows each token's name, permissions, expiry and last use.

Using a token

Send the token in the Authorization header:

curl -H "Authorization: Bearer glpat_<TOKEN>" \
  "https://api.chain.goledger.io/api/gofabric/v1/channels"

Tokens cannot be used on account routes (/api/auth, /api/stripe and /api/users), whatever their permissions, so a leaked token cannot take over your account.

Revoking a token

In Settings → Access Tokens, click Revoke on the token and confirm. Anything using it stops working immediately. This cannot be undone. Expired tokens stop working on their own.

Request Methods

Routes that change state accept only POST, PUT or DELETE, so that read-only credentials cannot change anything. In particular, starting and stopping a container and re-running a machine's setup are POST requests:

Action Route
Start or stop a GoFabric component POST /api/gofabric/v1/containers/{component}/{id}/start and /stop
Start or stop a GoBesu node or ETH API POST /api/gobesu/v1/containers/{component}/{id}/start and /stop
Re-run a machine's setup POST /api/goinfra/v1/machines/{id}/setup (requires write permission on the machine)

Errors

Status Meaning
401 Missing credential, or an invalid, expired or revoked personal access token.
403 access keys only reach their org's resources… An access key was used outside its organization's resources. Use a personal access token.
403 personal access token is read-only A read-only token was used for a request other than GET.
403 personal access tokens cannot be used to manage the account A token was used on /api/auth, /api/stripe or /api/users.

For integration support, contact support@goledger.com.br.