API Reference

NextEpoch exposes a small set of stable integration surfaces for automation. Portal-internal APIs can change as the product evolves; use the documented interfaces below for scripts and external systems.

Service Endpoints

Copy service endpoints from the portal before wiring automation. Endpoint hostnames can differ by environment, region, and organization policy.

Surface	Where to find it	Purpose
Identity	Settings > Organization > Credentials	OAuth tokens, service credentials, and organization identity APIs.
Registry	Apps > Catalog > Push image	Docker Registry V2-compatible image push and pull.
S3 Gateway	Storage > Object Storage	S3-compatible object storage endpoint.

Authentication

Use OAuth client credentials for server-to-server calls.

IDENTITY_URL="https://<identity-endpoint>"

curl -X POST "$IDENTITY_URL/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=organization:read"

The response contains an access token. Send it in the Authorization header:

Authorization: Bearer <access-token>

Create and revoke client credentials from Credentials & Webhooks.

Permissions

When you create a credential, select the smallest permission set needed for the automation task. Available permissions are shown in the credential dialog and are constrained by organization membership, service policy, and project visibility.

Docker Registry

The registry implements Docker Registry V2 behavior for organization images.

Image naming:

{registry-domain}/orgs/{org-slug}/{app-slug}:{tag}

Example:

REGISTRY_DOMAIN="<registry-domain>"

docker login "$REGISTRY_DOMAIN"
docker tag my-app:latest "$REGISTRY_DOMAIN/orgs/my-org/my-app:v1.0.0"
docker push "$REGISTRY_DOMAIN/orgs/my-org/my-app:v1.0.0"

See Docker Registry for details.

S3-Compatible Storage

Provisioned object storage is available through the S3 endpoint.

S3_ENDPOINT="https://<s3-endpoint>"

aws s3 --endpoint-url "$S3_ENDPOINT" ls

Each provisioned app appears as a bucket at the shared endpoint. See Provisioning Storage for examples.

Webhooks

Incoming webhooks accept HTTP POST requests at the generated webhook URL.

Use webhooks for automation that sends events into your workspace. Keep webhook URLs secret and rotate them if they are exposed.

See Credentials & Webhooks.

Error Handling

Status	Meaning
400	Invalid request body, path, or parameter.
401	Missing or invalid token.
403	Token is valid but lacks scope, role, organization, or project access.
404	Resource does not exist or is intentionally hidden by access control.
409	Conflict, such as duplicate slug or concurrent update.
429	Rate limit exceeded.
5xx	Platform or upstream service error. Retry only if the operation is safe.

Troubleshooting

Symptom	What to check
Token request fails	Confirm client ID, client secret, grant type, and scopes.
API returns 403	Check credential permissions and organization role. For project resources, check project membership.
Registry push returns denied	Confirm image name, registry login, and push access.
S3 client cannot connect	Confirm endpoint URL, access key, secret key, and bucket name.
Automation suddenly fails	Check Audit Logs for credential revocation or role changes.

Next Steps

• Create API credentials
• Push images
• Use S3 storage