Addresses
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:
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. 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
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. The secret is shown once.External App
Use an External App for unattended software. An administrator registers it under Platform → Developers → 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.Understand the layers
- Identity: the credential resolves to a person, External App, or other supported actor.
- Roles and grants: roles contain permissions; grants place them at a scope.
- Token or key scopes: scopes narrow the permissions the credential can exercise. Asking for a scope never grants a role.
- Resource reach: some reads and writes are further limited by ownership, organizational home, relationship, or other resource rules.
- Runtime governance: Trust Fabric can allow, refuse, or hold a concrete action.
Verify access safely
Call a read operation the integration needs and confirm both the successful response and the expected denial outside its scope. Preservemeta.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:
- Does a role contain the permission?
- Is that role granted at the resource’s required scope?
- Does the token/key scope include it, or did the credential narrow it away?
- Is the actor allowed to reach this resource?
- Did runtime policy refuse or hold the action?
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.
Related
- Personal keys: create and revoke your own key.
- Permission reference: every permission and the roles that hold it.
- Credential kinds: which credentials each operation admits.

