Automation
Automation
Automate Apiable two ways: the Platform API, a per-portal add-on at your-portal.api.apiable.io for managing subscriptions, teams, users, webhooks and API Catalog entries from code, and webhooks that notify your systems when events happen.
You can automate Apiable two ways. Call the Platform API to manage your API program from code or a pipeline, and register webhooks so Apiable notifies your systems when something happens. Most automations use both: a webhook tells you something changed, and the Platform API lets you act on it.
How do I automate Apiable?
Two ways. The Platform API is a REST API you call to read and change your portal's data. Webhooks go the other way: Apiable sends a POST to your endpoint when an event happens, so you do not have to poll.
| Approach | Direction | Use it to |
|---|---|---|
| Platform API | You call Apiable | Manage subscriptions, teams, users, webhooks, documentation and API Catalog entries from your own code or CI. |
| Webhooks | Apiable calls you | Hear about subscription, invoice and scope grant events as they happen. |
How do you get access to the Platform API?
Ask Apiable to enable it for your portal. Apiable sets up your endpoint, https://your-portal.api.apiable.io, and gives you a subscription on its own API Portal, developer.apiable.io. That subscription's client ID and secret are your Platform API credentials.
- Contact Apiable and ask for the Platform API for your portal.
- Sign in to developer.apiable.io and open your subscription to your portal's Platform API.
- Copy the Client ID and Client Secret, and store them in your secret manager or CI secrets.
The endpoint name uses your portal's name, the same one in your-portal.apiable.io. There is no shared api.apiable.io endpoint.
How do you call the Platform API?
Exchange your client ID and secret for an access token, then call your portal's endpoint with it as a Bearer token. Request a fresh token when it expires. The response's expires_in gives its lifetime in seconds.
curl -X POST "https://developer.apiable.io/api/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=client_credentials \
-d client_id="$APIABLE_CLIENT_ID" \
-d client_secret="$APIABLE_CLIENT_SECRET"Send the access_token from the response on each call:
curl "https://your-portal.api.apiable.io/api/subscriptions" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-API-Version: 2024-09-25"The X-API-Version header is optional on your portal's endpoint, which uses 2024-09-25 when you leave it out. Send the access token, never the client secret, in the Authorization header.
What can the Platform API manage?
Subscriptions, teams, users, companies, invitations, webhooks, plan documentation and API Catalog entries, which you can create and change. Products and plans are read-only, apart from each plan's documentation entries.
| Resource | What you can do |
|---|---|
| Products | Read. |
| Plans | Read, and manage each plan's documentation entries. |
| Subscriptions | Create, read, update, approve, reject, cancel, refresh billing status, set custom properties, and report usage. |
| Teams | Create, read and update teams, and add or remove members. |
| Users | Read and update developer accounts, approve or reject them, and set their roles. |
| Companies | Create, read and update. |
| Invitations | Create, read and update. |
| Webhooks | Create, read, update and delete, send a test delivery, and read delivery history. See Webhooks. |
| API Catalog | List entries, add an API that no gateway reports, publish a specification, read its versions, and manage operation overrides. See CI/CD documentation sync. |
| Documentation | Point a documentation entry at a new specification, and configure the Full API Reference. |
| Files | Upload a file under 1 MB. It is stored at a public address, so anyone with the link can read it. |
The Platform API reference lists the endpoints, request bodies and responses.
When should I use webhooks instead?
Use webhooks when you want to react to a change as it happens rather than poll for it. Apiable posts to the URL you register when an event fires, such as a new subscription or an approved scope grant.
Each delivery carries the event's type and Standard Webhooks signature headers. Deliveries are not filtered per webhook: a webhook can receive event types it did not list, so your endpoint should check type and ignore events it does not handle. See Webhooks to register an endpoint.
How do the Platform API and webhooks work together?
A webhook tells you something changed, and the Platform API lets you act on it. Subscribe a webhook to SUBSCRIPTION_CREATED, and when one arrives, read the current subscriptions through the Platform API and provision access in your own systems.
This removes polling on a schedule. You wait for the event, then make the Platform API calls you need to read the current state.
How do I keep my docs in sync from CI/CD?
Publish your OpenAPI specification from your pipeline through the Platform API. Portals whose documentation follows the API Catalog publish to the API's catalog entry. Other portals point a plan's Continuous Delivery documentation entry at the new specification.
See CI/CD documentation sync for both flows and a GitHub Actions example.