> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Access and credentials

> Find the Forge addresses, get an account, choose a Personal key or External App, and understand roles, scoped grants, token scopes, and runtime decisions.

Authentication answers who is calling. Authorization then combines the actor's roles and scoped
grants, credential scopes, resource reach, and runtime policy. A valid token is not a grant.

## Addresses

| Surface | Address | Use it for |
| - | - | - |
| Console | `https://forge.gloo.com` | Person sign-in, authoring, configuration, and operations |
| HTTP API | `https://api.forge.gloo.com` | API v3 and `/oauth/token` |
| Hosted MCP | `https://mcp.forge.gloo.com/mcp` | Streamable HTTP MCP hosts |

For non-production deployments, use the environment address supplied by your administrator. Do not
assume a purpose hostname is active from its name alone.

## Mint an External App token

An External App exchanges its client id and secret at `/oauth/token` for a short-lived bearer:

```bash theme={null}
curl -fsS -X POST "https://api.forge.gloo.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$FORGE_CLIENT_ID" \
  -d "client_secret=$FORGE_CLIENT_SECRET" \
  -d "scope=agents:read runs:read"
```

Use the returned `access_token` as `Authorization: Bearer <token>` and renew it according to its
`expires_in`. Requested scopes only narrow the app's role grants. Keep the client secret and bearer
server-side.

## Get a person account

Forge access is administered by the organization. Ask an administrator to invite or provision the
email identity you will use, and to tell you which organizational scope and roles were granted.
Sign in through the Console with that identity, then review [Your access](https://docs.gloo.com/forge/console/settings/your-access.md).

Account invitation, notification delivery, default-role policy, and allowed email domains are
deployment policy. Not every deployment sends an invitation email, grants the same default roles,
or accepts the same domain. If sign-in succeeds but no Forge resources are visible, ask the
administrator to check the identity link and scoped grants rather than creating a second identity.

## Choose the actor

| Actor and credential | Use it for | Do not use it for |
| - | - | - |
| Person session | Console and interactive hosted MCP | Unattended services |
| Personal key (`fmcp_…`) | A person's scripts or MCP host where the operation allows a person | Shared automation or operations restricted to External Apps |
| External App client credentials | Services and local MCP stdio | Pretending to be a person; human-only decisions |
| Platform API key | Narrow platform operations documented as supporting it | General application integration unless explicitly intended |

Hosted MCP can use interactive OAuth without embedding a secret in host configuration. Some
operations require a person; some administration operations require an External App instead.
Check the operation's credential kinds.

### Personal key

Use a Personal key for a person's script or supported MCP host. It acts as its owner and can only
exercise the owner's authority, narrowed by the key's scopes. Create and revoke keys under
[Settings → Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md). The secret is shown once.

### External App

Use an External App for unattended software. An administrator registers it under
[Platform → Developers → External Apps](https://docs.gloo.com/forge/console/platform/external-apps), gives it roles at explicit
scopes, and provides its client id and one-time client secret through an approved secret channel.
A new app has no useful authority until roles are granted. Mint its bearer as shown
[above](#mint-an-external-app-token).

## Understand the layers

1. **Identity:** the credential resolves to a person, External App, or other supported actor.
2. **Roles and grants:** roles contain permissions; grants place them at a scope.
3. **Token or key scopes:** scopes narrow the permissions the credential can exercise. Asking for a
   scope never grants a role.
4. **Resource reach:** some reads and writes are further limited by ownership, organizational home,
   relationship, or other resource rules.
5. **Runtime governance:** Trust Fabric can allow, refuse, or hold a concrete action.

Use the [permission reference](https://docs.gloo.com/forge/reference/permissions) for the permission catalog and the
[credential-kind reference](https://docs.gloo.com/forge/reference/credential-kinds.md) for operation compatibility.

## Verify access safely

Call a read operation the integration needs and confirm both the successful response and the
expected denial outside its scope. Preserve `meta.requestId`. A `401` is a credential problem; a
`403` means the actor authenticated but lacks effective authority.

## Diagnose `401`

A `401` means the credential did not authenticate for this request. Check the API origin, bearer
header, expiry, revoked key, client id/secret, and hosted MCP sign-in. Re-mint an External App token
when expired; do not retry a write merely because its response was lost.

## Diagnose `403`

A `403` means Forge identified the actor but the action was not authorized. Preserve
`meta.requestId`, read the required permission and denial details, then check:

1. Does a role contain the permission?
2. Is that role granted at the resource's required scope?
3. Does the token/key scope include it, or did the credential narrow it away?
4. Is the actor allowed to reach this resource?
5. Did runtime policy refuse or hold the action?

Do not solve a narrow denial by granting a platform-wide administrator role. Use
[Your access](https://docs.gloo.com/forge/console/settings/your-access.md) and the denial explanation surfaces to find the
smallest correction.

## Operate credentials safely

* Store secrets in a secret manager and never in browser bundles, prompts, or logs.
* Give each integration its own External App so ownership and audit are attributable.
* Request only the token scopes the client needs.
* Plan rotation and revocation before production use.
* Test human-only and app-only restrictions with the credential that will actually run the job.

Continue with the [Quickstart](https://docs.gloo.com/forge/quickstart.md).

## Related

* [Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md): create and revoke your own key.
* [Permission reference](https://docs.gloo.com/forge/reference/permissions): every permission and the roles that hold it.
* [Credential kinds](https://docs.gloo.com/forge/reference/credential-kinds.md): which credentials each operation admits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.