Help Center / API and developers /
API client management
API clients are the credentials that external tools and integrations use to authenticate with Plutio's REST API and receive webhook events. Each client can be enabled for specific workspaces, and the event method list controls which outbound webhook events are sent.
Creating an API client
API clients are created from Settings > API manager. Each client is given a name for identification, and Plutio generates a client ID and client secret. Both stay visible on the client page whenever you need them. Treat the secret like a password and keep it private.
Workspace access
Each API client can be enabled for one or more workspaces. API requests still need a business header, and that header must match one of the workspaces enabled for the client. If the request sends a missing or different subdomain, Plutio returns a 400 workspace error even when the OAuth token is valid.
For example, a request for the-ceramic-school must include business: the-ceramic-school, and the API client must be enabled for that workspace.
Permissions and scoping
API client access is scoped by workspace, not by individual REST API area. The Workspaces selector controls which workspaces the client can be used with. The method checklist controls outbound webhook events only; it does not create read-only REST API access and it does not limit the REST API to invoices, projects, tasks, or other entity groups.
Webhook events vs API access
The method checklist in the API client controls webhook events only. Methods such as task.create, task.edit, and task.remove decide which outbound webhook payloads Plutio sends to the webhook URLs on that client.
Those method selections do not make the REST API read-only, and they do not block REST API endpoints. Plutio does not currently support per-client read-only API access. If no webhook methods are selected, the API client can still authenticate and call the REST API, but webhook deliveries for those events will not be queued.
Token lifecycle
Access tokens are obtained by sending the client ID and client secret to the /oauth/token endpoint using the client_credentials grant type. Each token is valid for 72 hours. When a token expires, a new token is requested using the same credentials. Integrations that run continuously should handle token refresh automatically to avoid interruptions.
Managing multiple clients
Multiple API clients can exist simultaneously, each with its own workspaces, webhook URLs, webhook event methods, and API version. A CRM sync client, a billing integration client, and a reporting client can all operate independently. Revoking one client's access does not affect the others.
Troubleshooting client access
When an API client authenticates but a request fails, check the workspace selection before regenerating credentials. The client ID and secret may be correct while the request still targets a workspace that is not enabled for that client.
- Use Common API errors when the response includes
Business undefinedorBusiness X is not enabled for this client. - Use Webhook integration when the token works but expected webhook events are not sent.
- Create a new client if the client secret was lost. Plutio only shows the secret when the client is created.
