Pages in this manual

For owners

For developers

About

For developers

Register an app (OAuth)

Let many Forge customers connect your product, each approving it for their own company.

Use OAuth if you build a product that serves many Forge customers. Each contractor approves your product for their own company on Forge's own page, and can end that approval at any time. If you only need your own company's data, an API key is simpler: see use an API key instead.

How Forge knows your app

Forge first looks for a Client ID Metadata Document: your app's client_id is an https address where your app publishes its own name and the addresses it returns to. Forge fetches that document, checks that it names the same client_id, and keeps a copy for a while before fetching it again.

An app that does not present one can register itself with dynamic registration instead. A registration that no contractor approves within 24 hours expires.

Rules for names and return addresses

  • A return address is https, a loopback address on the person's own computer (127.0.0.1 or [::1]), or a private reverse-domain scheme for an app installed on a computer or phone. It must match exactly, except the port of a loopback address.
  • Return addresses with a user name, a fragment, a wildcard or any other IP address are refused.
  • An app's name is at most 64 characters.
  • An app Forge has not verified cannot use a name that is, or contains, the name of a verified app or the word Forge. Capital letters and look-alike characters do not get around it. See how verification works.

The flow

It is the authorization code flow with PKCE, and only S256 is accepted.

  1. Send the contractor to https://api.forge.equipment/oauth/authorize with your client_id, your return address, a code challenge and scope forge.read. Set resource to the address of the door you want: https://api.forge.equipment/v1 for the public API, or https://api.forge.equipment/mcp for the MCP server. A request that names no resource gets a token for the MCP server only.
  2. The contractor signs in to Forge, picks one company, reads what your app can read and chooses Allow read access. Every refusal is shown to them on Forge's page, and nothing is sent back. If they choose Cancel, your app gets access_denied.
  3. Exchange the code at https://api.forge.equipment/oauth/token. The access token lasts one hour. The refresh token rotates each time you use it and expires after 30 days unused.

A token works only on the door it was issued for. A token for the public API is refused by the MCP server, and the reverse. Forge's authorization server publishes all of its endpoints, revocation included, at /.well-known/oauth-authorization-server on the API's address.

What the contractor sees

Forge's page shows your app's name, where the connection returns to, and "Unverified app" unless Forge has verified your app. It lists what your app can read and what it can never read, and says that your app reads the whole company it is approved for. After Allow, the connection appears in Forge's Settings for every owner and admin of that company, who can end it at any time.