Custom APIs

Explore authentication, permissions and available actionsExact inputs, sign-in scopes, access limits and approval rules.

For a tool with no MCP server, or a system of your own, connect its API. Hires then read from it and send to it through Roster, always under the address you give and only on the paths you allow. The key stays in Roster.

Connect oneCopy Anchor Link

1. Open Integrations → Tools → Add a tool and choose Custom API. (Catalog entries like WhatsApp Business, Twilio or Shopify are custom APIs with the address filled in.)

2. Base address: where the API lives, like https://api.example.com/v1. Every call stays under it.

3. How it signs in:

   Choice	Fill in
   Bearer token	the token
   API key in a header	the key, and the header's name (like X-API-Key)
   Username and password	both
   OAuth client credentials	the token address, client ID and secret, and a scope if any
   No sign-in	nothing

4. OpenAPI document (optional): its address. You can also upload the file when you test.

5. Extra headers (optional): anything else every call needs, one per line as Name: value. Not for secrets: those go in the sign-in fields above, which are sealed.

Test itCopy Anchor Link

Click Test connection. With an OpenAPI document (by address, or uploaded on the spot), Roster reads it and lists one tool per operation, with Reads for GET operations and Changes things for the rest. Untick any no hire should use, and click Save tools.

Without a document, Roster checks that the API answers, and hires get two tools: one to read (GET) and one to send (POST, PUT, PATCH or DELETE, with a JSON or form body).

Give hires accessCopy Anchor Link

On each hire's Tools tab, give access to the connection:

• Read only: only GET requests.
• Read and write: everything.
• Paths: only these path prefixes, like /invoices. Calls anywhere else are refused.
• Tools: with a document, which operations this hire may use.

On the connection, Ask before using set to Tools that change things makes every POST, PUT, PATCH or DELETE wait for a person's approval in chat; when the approver says yes, Roster sends exactly that request, once. New connections start with it; once you trust your hires with the API, change it to Only tools a hire is set to ask about. Connections made before this was the default keep what they had. For single operations, or one hire only, use When it asks first on the hire's Tools tab.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Custom API and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API authentication

Choose the API's sign-in method in the connection fields below. The available choices, credential fields and scope field are shown there; they depend on your service rather than a fixed OAuth permission list.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Custom API connection fields

Field	What to provide
Base address baseUrl Required	Every call stays under this address. Addresses on your own network work too.
How it signs in authType Optional	Use the value for your account or connection. Choices: Bearer token (bearer); API key in a header (header); Username and password (basic); OAuth client credentials (client_credentials); No sign-in (none). Starts with: bearer.
Token or key token Optional · sealed secret	Use the value for your account or connection. Shown when authType: bearer or header.
Header name headerName Optional	Use the value for your account or connection. Starts with: X-API-Key. Shown when authType: header.
Username username Optional	Use the value for your account or connection. Shown when authType: basic.
Password password Optional · sealed secret	Use the value for your account or connection. Shown when authType: basic.
Token address tokenUrl Optional	Use the value for your account or connection. Shown when authType: client_credentials.
Client ID clientId Optional	Use the value for your account or connection. Shown when authType: client_credentials.
Client secret clientSecret Optional · sealed secret	Use the value for your account or connection. Shown when authType: client_credentials.
Scope scope Optional	Use the value for your account or connection. Shown when authType: client_credentials.
OpenAPI document openapiUrl Optional	Its address, so hires get one tool per operation. Or upload the file when you test the connection.
Extra headers headers Optional	Sent with every call, one per line as Name: value. Not for secrets: put those above.
Ask before using askFirst Optional	With “Tools that change things”, a hire's call to any tool here that changes something waits for a person's approval in chat, and runs exactly as asked once approved. New connections start there; choose the other option once you trust the hires with this connection. Each hire's Tools tab can also ask for single tools. Choices: Only tools a hire is set to ask about (never); Tools that change things (writes). Starts with: writes.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Custom API per-hire limits

Field	What to provide
Tools tools Optional	Leave empty for every tool on this connection.
Paths paths Optional	Path prefixes this hire may call, like /invoices. Leave empty for the whole API.

Actions

Actions come from your OpenAPI document. Without a document, hires use general read (GET) and send (POST, PUT, PATCH, DELETE) actions on the paths you allow.

Use Test connection to inspect the exact names, descriptions and read/write classifications; select the actions and Save tools. Retest when the service changes. A server's read-only labels are supplied by that server: review them before granting access.

Watches and incoming events

• No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
• No incoming webhook handler is declared for this integration.

Limits and troubleshooting

• Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
• Expired or revoked access: reconnect or replace the key on the connection.
• Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
• The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation