ZevCloud
Dashboard

Build on ZevCloud

Build on ZevCloud with connected apps

How partner apps, such as AI builders and developer tools, create, deploy and watch services in a person's ZevCloud team with their consent.

A connected app is a partner app that acts in a person’s ZevCloud account with their consent. An AI builder can create a service from the code it wrote, set its environment variables, deploy it and read its logs. The person stays in control. They pick which teams the app may touch, and they can disconnect it at any time.

This page covers using ZevCloud once your app is connected. Getting approved, connecting a person, PKCE, tokens, refresh, webhooks and testing are covered in ZevAuth’s guide, Delegated access to Zev products.

How it works

  1. Your app is approved for ZevCloud through ZevAuth. See Getting approved.
  2. Your app sends the person to connect. ZevID signs them in, shows the permissions you ask for and lets them pick teams. See The flow.
  3. ZevAuth gives your app a 10 minute access token and a refresh token. See Using the access token and Refresh tokens.
  4. Your app calls the ZevCloud API with that token and a team id.

Quick start: from connected to deployed

Once the person has connected, getting their code live is four calls, plus one check before you create. You don’t need a plan id (the free plan is the default), you don’t look up environments, and the person doesn’t have to connect GitHub to ZevCloud.

  1. Check limits before creating. GET /teams/current/limits (with x-team-id) tells you whether the team has free services left, and how many projects and unpaid services your app holds there. If freeServices.remaining is 0, a free create will be refused, so show the person their options first. See Common questions.
  2. Create a project, once per team. POST /projects with { "name": "..." }. It comes with a Production environment. Save id and environments[0].id from the response, because your app can’t list projects later. Reuse this project for that team’s next services.
  3. Create the service in that environment: POST /environments/<environmentId>/services/application. Pick a source from Choosing a source. planId is optional: leave it out for the free plan, or pass a paid plan and the service waits for the person to pay (see Money).
  4. Set environment variables if the app needs them (POST /services/<serviceId>/env/bulk).
  5. Deploy (POST /services/<serviceId>/deployments) and follow the deployment until it reports running.

The end-to-end example shows each request and response.

Common questions

  • What is planId, and where do I get one? It’s optional. Leave it out and the service uses the free plan. To offer a paid plan, take its id from GET /public/pricing/deployment-plans?market=<code> (no token needed; it also lists names, limits and prices), using the team’s market.code from GET /teams/current/limits. A paid create returns a payment block with a link for the person to pay, and the service deploys once they do. See Money.
  • What is environmentId? The id of an environment inside a project, not a name like “production” or “staging”. A project your app creates has one environment, Production, and its id is environments[0].id in the POST /projects response.
  • Do I have to create a project first? Yes, once. Every service lives in a project. Create one the first time you deploy for a team, store its ids, and reuse it.
  • What if the person has used all their free services? Each team has a limited number of free services, shared by every service type. Check first with GET /teams/current/limits: when freeServices.remaining is 0, a free create returns 402 free_limit_reached with limit, used, market, plansUrl, databasePlansUrl, manageServicesUrl and dashboardBillingUrl. Show the person their two options. They can choose a paid plan: take a plan id from plansUrl (already filtered to the team’s market), create with planId, and show them the payment link from the response (see Money). Or they can delete a free service they no longer need at manageServicesUrl, then you try the create again.
  • Does the person have to connect GitHub to ZevCloud? No, unless you choose to build from their GitHub with sourceMode: "github". Uploads and public URLs need no GitHub connection on ZevCloud.

Choosing a source

SourcesourceModeNeeds from the personUse it when
UploaduploadNothingYour app already has the code (you generated it, or you read it from GitHub yourself). You send a tarball; ZevCloud builds it. Set frameworkPreset to one of nextjs, astro, nuxt, remix, sveltekit, vite, node, python, fastapi, django, flask, go, php or ruby.
Public URLpublic-urlNothingThe code is in a public Git repository. Any language.
GitHubgithubZevCloud’s GitHub App installed on the repository, and the zevcloud.repos.read scopeYou want ZevCloud to build a private repository directly. See Building from GitHub.

If your app already has access to the person’s GitHub, upload is the smoothest path: fetch the repository archive with your own access, then send it to ZevCloud. The person connects GitHub once, to your app, and nowhere else. Upload flow: create the service with sourceMode: "upload", POST /services/<serviceId>/uploads/url to get an upload URL, PUT the tarball to it, POST /services/<serviceId>/uploads/<uploadId>/complete, then deploy with { "sourceUploadId": "<uploadId>" } in the body of POST /services/<serviceId>/deployments.

Uploading a backend

Uploads build web frontends and backends alike. Pick the frameworkPreset that matches the code:

PresetDefault portInstalls withStarts with (when you send no startCommand)
fastapi8000uv.lock, poetry.lock, requirements.txt or pyproject.toml, in that orderuvicorn main:app, or app.main:app when the app is in app/main.py
flask8000Same as FastAPIgunicorn app:app
django8000Same as FastAPI, then collectstatic when the settings allow itgunicorn <project>.wsgi, with the project found from manage.py
python8000Same as FastAPINothing. Send a startCommand, or the create is refused with a 400.
go8080go mod downloadThe main package, built as a static binary
php80composer install without dev packagesA PHP web server for public/, or the top folder when there is no public/
ruby3000bundle install without the development and test groupsbin/rails server for Rails, otherwise rackup with config.ru

The server packages the default start commands need (uvicorn, gunicorn) are added when your project doesn’t list them. The app runs as a non-root user and gets its port in PORT. Any default can be replaced with installCommand, buildCommand or startCommand, and rootDirectory points the build at a folder inside the tarball.

Pick the language version with runtimeVersion. Leave it out for the default:

RuntimeVersionsDefault
Python (python, fastapi, django, flask)3.10, 3.11, 3.12, 3.133.12
Go1.23, 1.24, 1.25, 1.26, 1.271.27
PHP8.2, 8.3, 8.48.3
Ruby3.2, 3.3, 3.43.3

Any other version is refused with a 400 that lists the choices. For example, a FastAPI backend:

{
  "name": "Recipe API",
  "slug": "recipe-api",
  "sourceMode": "upload",
  "frameworkPreset": "fastapi",
  "runtimeVersion": "3.12",
  "rootDirectory": "backend"
}

Send it to POST /environments/<environmentId>/services/application, then upload and deploy as above. A few things to know:

  • Python packages with C code compile during the build when they ship no ready-made wheel. Packages that also need a system library at runtime (for example psycopg2 built from source, which needs libpq) won’t load. Use the binary build instead, such as psycopg2-binary or psycopg[binary].
  • Go builds with cgo off, so the binary is static. Packages that need cgo, such as mattn/go-sqlite3, won’t build; use a pure Go driver like modernc.org/sqlite. Read the port from PORT.
  • PHP includes pdo_mysql, pdo_pgsql, mysqli, bcmath, intl, zip, gd, exif, pcntl and opcache, on top of the usual built-in extensions. Requests that aren’t for a real file go to index.php, which is what Laravel and Symfony expect.
  • Ruby must match the version in your Gemfile, if it names one. Rails needs SECRET_KEY_BASE set as an environment variable.
  • Django needs your service’s address in ALLOWED_HOSTS.

Teams

ZevCloud’s targets are teams.

  • The person picks teams on the ZevID consent screen.
  • Only teams where they are an owner or admin can be picked.
  • If your app asks for zevcloud.services.delete, only teams the person owns can be picked. Teams where they are only an admin show but cannot be chosen.
  • If they have no team yet, they can create one from the consent screen. It opens ZevCloud’s create-team page and brings them back to finish connecting.
  • On every call, the team must be one the person connected, and they must still be an owner or admin of it. If they lost that role, the call fails with role_lost.

Scopes

Ask only for the scopes your app needs. The person sees each one on the consent screen. See also Scopes by product.

ScopeRiskWhat it allows
zevcloud.services.readstandardRead services, deployments, build logs, runtime logs, metrics and environment variable names. Values are always masked.
zevcloud.services.createstandardCreate projects and services, from public URLs or uploads, on the free plan or any public paid plan or database tier. Paid services wait for the person to pay.
zevcloud.repos.readhighBuild from GitHub repositories the team’s ZevCloud GitHub App can see, and list them. A build can print the whole repository into logs your app reads.
zevcloud.deploystandardDeploy, roll back, approve or reject deployments, and start, stop and restart services.
zevcloud.env.writestandardSet and delete environment variables. ZevCloud never returns values, but your build and runtime logs show whatever your code prints.
zevcloud.services.deletehighDelete services the app created, only on teams the person owns.
zevcloud.services.allhighAct on every service in the team, not only the ones the app created.

Routes by scope

All paths are relative to https://api.zevcloud.net/v1.

zevcloud.services.read

  • GET /environments/:environmentId/services
  • GET /environments/:environmentId/services/:serviceId
  • GET /environments/:environmentId/services/:serviceId/currently-running
  • GET /services/:serviceId
  • GET /services/:serviceId/payment
  • GET /teams/current/limits (also works for people signed in to ZevCloud)
  • GET /services/:serviceId/sync-status
  • GET /services/:serviceId/metrics
  • GET /services/:serviceId/runtime-logs
  • POST /services/:serviceId/logs/session
  • GET /services/:serviceId/deployments
  • GET /services/:serviceId/deployments/:deploymentId
  • GET /services/:serviceId/deployments/:deploymentId/logs
  • POST /services/:serviceId/deployments/:deploymentId/logs/session
  • GET /services/:serviceId/env (names only, values masked)

zevcloud.services.create

  • POST /projects creates a project with its Production environment. The response includes environments[0].id.
  • POST /environments/:environmentId/services/application
  • POST /environments/:environmentId/services/wordpress
  • POST /environments/:environmentId/services/database
  • POST /environments/:environmentId/services/upload
  • POST /services/:serviceId/uploads/url
  • POST /services/:serviceId/uploads/:uploadId/complete

zevcloud.repos.read

  • GET /github/repos lists the repositories ZevCloud can see for this team.
  • GET /github/repos/:owner/:repo/branches
  • GET /github/repos/:owner/:repo/access checks one repository before you create a service from it. See Building from GitHub.
  • With this scope, POST /environments/:environmentId/services/application also accepts sourceMode: "github". Deploying, rolling back or approving a deployment of a service that builds from GitHub needs it too.

zevcloud.deploy

  • POST /services/:serviceId/deployments. The body may include commitSha to roll back, but only to a commit your app deployed.
  • POST /services/:serviceId/deployments/:deploymentId/approve
  • POST /services/:serviceId/deployments/:deploymentId/reject
  • POST /services/:serviceId/start
  • POST /services/:serviceId/stop
  • POST /services/:serviceId/restart
  • POST /services/:serviceId/deploy
  • POST /services/:serviceId/wp-restart-db

zevcloud.env.write

  • POST /services/:serviceId/env
  • POST /services/:serviceId/env/bulk
  • DELETE /services/:serviceId/env/:envVarId

zevcloud.services.delete

  • DELETE /environments/:environmentId/services/:serviceId. Only on teams the person owns. Without zevcloud.services.all, only services your app created.

zevcloud.services.all

This scope has no routes of its own. It widens the other scopes from “services this app created” to every service in the team. Together with zevcloud.services.delete, your app can delete any service in teams the person owns, including ones the person created. Ask for both only if your app really manages the whole team.

High-risk scopes

zevcloud.repos.read, zevcloud.services.delete and zevcloud.services.all are high risk. People see them unticked on the consent screen.

  • The person must have signed in recently to grant them.
  • They end after a confirmation window (30 days by default).
  • After that, calls that need them return high_risk_confirmation_required. Send the person to confirm again through ZevAuth. See High-risk permissions.

Calling the API

Base URL:

https://api.zevcloud.net/v1

Send two headers on every call:

Authorization: Bearer <partner access token>
x-team-id: <team id>
  • The access token comes from ZevAuth and lasts 10 minutes. Refresh it through ZevAuth before it runs out.
  • x-team-id names the team you are acting on. It must be a team the person connected. ZevCloud never takes the team from the token or the request body.

What apps can never do

Some actions belong to the person alone. They are refused for every app, whatever scopes it holds, with not_available_to_partners:

  • Paying invoices, plan upgrades and anything else to do with billing
  • Zev Credit
  • Storage subscription changes
  • Buying or transferring domains
  • Team settings, members, invites and ownership
  • Creating or deleting teams
  • API keys
  • Terminal access and running commands
  • File access and downloads
  • WordPress credentials, auto-login and SFTP
  • Database public access and database credentials
  • ZevBox
  • Connecting or disconnecting GitHub, and linking GitHub accounts
  • Security settings
  • Saved addresses
  • Policies
  • Verification

Projects can be created but not listed or edited. Cross-team lists (/aggregate/*) are not available.

Building from GitHub

Building from a public URL or an upload needs nothing extra. Building from GitHub needs zevcloud.repos.read, a high-risk scope: your app chooses the build steps, so a build can print the whole repository into logs your app reads. If ZevCloud’s GitHub App is installed with access to all repositories, that can cover a whole organisation. Ask for it only if your app really builds people’s GitHub code.

Your app can only build repositories the team’s ZevCloud GitHub App can already see. Which repositories that is stays the person’s choice on GitHub, so you never get wider access than they gave ZevCloud.

Check a repository first:

curl "$ZC/github/repos/acme/api/access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM"

If ZevCloud can see it, you get { "ok": true }. Then create the service with sourceMode: "github" and gitRepoUrl: "https://github.com/acme/api". Private repositories get a read-only deploy key automatically.

If not, you get ok: false with an access value, a url and steps to show the person. Creating the service anyway returns the same details with 409 github_access_required.

accessMeaningurl opens
app_not_installedThe ZevCloud GitHub App is not installed on the account or organisation that owns the repository. The team owner connects GitHub in ZevCloud. On an organisation, an organisation owner approves the install.ZevCloud team settings, Integrations
repo_not_visibleThe app is installed on the owner, but this repository is not in its “Repository access” list. On an organisation, only an organisation owner can change the list.The installation’s settings page on GitHub

Show the steps as they come; they already cover personal accounts and organisations. When the person is done, check again.

If the person later removes access on GitHub, takes back zevcloud.repos.read, or lets its confirmation lapse, new builds from that repository stop, including approving a held deployment. While the confirmation has lapsed, those calls return high_risk_confirmation_required.

Only your own services

Every service your app creates is marked as created by your app.

  • Without zevcloud.services.all, every service route refuses services your app did not create, with not_created_by_partner.
  • Lists only include your own services.
  • With zevcloud.services.all, your app can act on every service in the team, within its other scopes.

Store the service ids your app creates. You cannot list projects to find them again.

Secrets and money

Secrets

ZevCloud never hands secrets to your app.

  • Environment variable values are never returned. Reads show names only.
  • Passwords, keys and connection strings are never returned to apps.
  • WordPress, database and file-transfer passwords for a new WordPress site are emailed to the person, never to an address your app chooses.
  • Billing details (plans, invoices, billing status) are left out of everything your app reads. The one exception is the payment block for a service waiting to be paid, described under Money.

Variables are still given to the code you build and run. If that code prints a value, it shows in build or runtime logs, which your app can read. Don’t print secrets.

Money

Your app never pays and never sees card details. The person pays ZevCloud directly, through ZevPay or the ZevCloud dashboard.

  • Plans and prices depend on the team’s market. Every team belongs to one market, chosen when the team was created, and is billed in that market’s currency. Which plans are sold, and at what price, can differ between markets. Read market.code and market.currency from GET /teams/current/limits and fetch plans with ?market=<code>, for example GET /public/pricing/deployment-plans?market=NG. Use only plans from that list. The team’s market always decides: nothing your app sends changes it, and a plan not sold there is refused with 400 plan_not_available and the market. Teams in a market that is not open can’t create services from your app (403 market_closed).

  • Free by default. Leave out planId and the service uses the free plan. Leave out databasePlanSlug and a database uses the free tier.

  • Paid plans are allowed. Pass a plan id from GET /public/pricing/deployment-plans, or a database tier from GET /public/pricing/database-plans (by databasePlanSlug or id). Plans that are retired or kept for a special offer are refused with 400 plan_not_available. An unknown database tier is a 400.

  • The service waits for payment. A paid service is created with status: "pending_payment". It can’t be deployed until the person pays. You can still upload code to it while it waits.

  • The create response carries a payment block when payment is needed:

    "payment": {
      "required": true,
      "status": "pending",
      "invoiceId": "6f1c...",
      "planName": "Starter",
      "amount": 5000,
      "currency": "NGN",
      "paymentUrl": "https://...",
      "payInDashboardUrl": "https://console.zevcloud.net/billing?invoice=6f1c..."
    }

    amount is in whole units of currency (naira, dollars), not kobo or cents. currency is the invoice’s currency, which is the team’s billing currency; don’t assume naira. Show paymentUrl to the person, or send them to payInDashboardUrl to pay in ZevCloud. When a ZevPay link can’t be used, paymentUrl is the dashboard link too. The team owner also gets the invoice by email, marked as created by your app.

  • Find out when it’s paid. Poll GET /services/<serviceId>/payment (needs zevcloud.services.read). It returns the same block while the payment is pending, then { "required": false, "status": "paid" }. A service that never needed payment returns { "required": false, "status": "none" }. GET /services/<serviceId> shows the service leave pending_payment at the same time. ZevCloud doesn’t send your app an event for this yet.

  • After payment ZevCloud deploys the service for you. An upload service deploys the latest upload you completed while it waited. If you didn’t upload anything, it stays stopped and ready: upload and deploy as usual.

  • Deploying before payment returns 402 payment_required with the same payment block.

  • A few unpaid services at a time. Your app can hold 3 services waiting for payment in each team (unless ZevCloud changes it). Past that, a paid create returns 409 unpaid_limit_reached with the limit. A slot frees up when the person pays, or when you or the person delete one of those services (your app needs zevcloud.services.delete). Deleting a service that was never paid cancels its invoice, so nothing is owed.

  • Unpaid services don’t wait forever. By default, after 7 days unpaid the team owner gets one email reminding them to pay, with the payment link and the date the service will be removed. After 14 days unpaid the service is removed, its invoice is cancelled and the owner is told. ZevCloud may change these defaults. A service that received any payment is never removed this way.

  • Uploaded code expires after 7 days. Code you upload while a service waits for payment is kept for 7 days. If the person pays later than that, upload and deploy again. A static site created with POST /environments/<environmentId>/services/upload keeps its ZIP while it waits and is published once paid. If the ZIP expired first, the site shows a placeholder page and GET /services/<serviceId>/payment returns "reuploadRequired": true with a message.

  • Test versions of your app create free services only. A paid planId or database tier from an app in test mode returns 400 paid_plans_live_only, because a paid plan raises a real invoice. See Testing.

  • Limits at a glance. GET /teams/current/limits returns what the team can still create:

    {
      "market": { "code": "NG", "currency": "NGN" },
      "freeServices": { "used": 3, "limit": 3, "remaining": 0 },
      "partnerProjects": { "used": 1, "limit": 10 },
      "partnerUnpaidServices": { "used": 0, "limit": 3 },
      "upgrade": {
        "plansUrl": "https://api.zevcloud.net/v1/public/pricing/deployment-plans?market=NG",
        "databasePlansUrl": "https://api.zevcloud.net/v1/public/pricing/database-plans?market=NG",
        "dashboardBillingUrl": "https://console.zevcloud.net/billing",
        "manageServicesUrl": "https://console.zevcloud.net/projects?view=services"
      }
    }

    freeServices.limit and remaining are null when the team has no free limit. A free create is refused exactly when remaining is 0. partnerProjects and partnerUnpaidServices are your app’s own counts in this team, and are null for people. market is the team’s market and billing currency, and the plan links are already filtered to it.

  • Your app can create a limited number of projects in each team (10 unless ZevCloud changes it). Past that, POST /projects returns 403 project_limit_reached with the limit. Reuse your projects.

Fair use

The person must have accepted ZevCloud’s fair use policy in the console. Until they do, calls return 403 fair_use_required. Send them to the ZevCloud console to accept it, then retry.

End-to-end example

This example creates a project, adds an application from a public Git repository, sets environment variables, deploys it and follows the deployment.

export ZC=https://api.zevcloud.net/v1
export TOKEN=<partner access token>
export TEAM=<team id>

1. Create a project

Needs zevcloud.services.create.

curl -X POST "$ZC/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{"name": "Recipe Finder"}'

The project comes with a Production environment. Keep environments[0].id from the response.

2. Create an application

Needs zevcloud.services.create. Use sourceMode: "public-url" to build from a public Git repository with no access setup.

curl -X POST "$ZC/environments/<environmentId>/services/application" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recipe Finder",
    "slug": "recipe-finder",
    "sourceMode": "public-url",
    "gitRepoUrl": "https://github.com/example/recipe-finder",
    "gitBranch": "main",
    "port": 3000
  }'

The slug becomes the service’s default address, <slug>.zevcloud.app. Other optional fields include rootDirectory, installCommand, buildCommand, startCommand, isStatic, isSpa, outputDirectory, runtime and runtimeVersion. Keep the service id from the response.

3. Set environment variables

Needs zevcloud.env.write.

curl -X POST "$ZC/services/<serviceId>/env/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"key": "NODE_ENV", "value": "production"},
      {"key": "RECIPES_API_KEY", "value": "rk_123", "isSecret": true}
    ]
  }'

The response lists the result for each item. Values are never sent back.

4. Deploy

Needs zevcloud.deploy.

curl -X POST "$ZC/services/<serviceId>/deployments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM"

Keep the deployment id from the response.

5. Follow the deployment

Needs zevcloud.services.read. Poll the deployment every few seconds until it reaches a final status: running, failed, cancelled or rolled_back.

  • queued, building and deploying mean keep polling.
  • pending_approval means the team approves deployments before they go out. Keep polling, or approve it with zevcloud.deploy if the person asked you to.
  • blocked means the team has an unpaid invoice. Stop and tell the person to check ZevCloud.
curl "$ZC/services/<serviceId>/deployments/<deploymentId>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM"

Read the build logs:

curl "$ZC/services/<serviceId>/deployments/<deploymentId>/logs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-team-id: $TEAM"

See Deployment statuses for every status.

Errors

Errors are JSON:

{
  "statusCode": 403,
  "code": "not_created_by_partner",
  "reason": "not_created_by_partner",
  "message": "This app can only act on services it created."
}

Branch on reason. The message is for people and may change.

ReasonStatusWhat to do
invalid_token401The token is not valid. Get a new one through ZevAuth.
stale_token401The connection changed. Refresh the access token through ZevAuth and retry once.
grant_not_found401The person disconnected your app. Ask them to connect again.
grant_not_found503ZevCloud could not confirm the connection with ZevID just now. Retry after a few seconds.
grant_revoked401The person disconnected your app. Ask them to connect again.
grant_suspended403The connection is suspended. Do not retry. Contact ZevID through ZevAuth.
grant_expired401A test connection ended. ZevAuth reports the same ending as test_grant_expired. Connect again.
not_available_to_partners403This action is for the person only. Send them to ZevCloud.
scope_not_granted403Your app does not hold the scope. Ask the person to connect again with it.
scope_paused403The permission is paused, for this connection or for your app everywhere (level: "approval"). Do not retry. See Paused permissions.
high_risk_confirmation_required403Send the person to confirm the high-risk permission again through ZevAuth.
team_required400Add the x-team-id header.
team_not_in_grant403The person did not connect this team. Ask them to add it.
team_suspended403The team is suspended. Do not retry. The person can see why in ZevCloud.
role_lost403The person is no longer an owner or admin of this team.
owner_required403Deleting needs the person to own the team.
not_created_by_partner403Your app did not create this service.
rollback_not_own_commit403You can only roll back to a commit your app deployed.
payment_required402The service is waiting for payment, so it can’t be deployed yet. Show the person payment.paymentUrl from the response, then poll GET /services/:serviceId/payment.
plan_not_available400That plan or database tier can’t be chosen, or isn’t sold in the team’s market (then the response has market). Pick one from GET /public/pricing/deployment-plans?market=<code> or GET /public/pricing/database-plans?market=<code>, or leave it out for the free one.
market_closed403The team’s market is not open, so your app can’t create services there. Do not retry. The person can contact ZevCloud.
free_limit_reached402The team has used all its free services. The response has limit, used, market, plansUrl, databasePlansUrl, manageServicesUrl and dashboardBillingUrl. Offer the person a paid plan (create again with planId), or send them to manageServicesUrl to delete a free service, then retry.
paid_plans_live_only400Your app is in test mode, which creates free services only. Leave out planId (or the database tier), or use the live version of your app.
unpaid_limit_reached409Your app already has limit services waiting for payment in this team. Wait for the person to pay, or delete one.
project_limit_reached403Your app has created as many projects as it can in this team. Reuse one.
github_access_required409ZevCloud can’t see the repository. Show the person the url and steps from the response.
fair_use_required403Send the person to the ZevCloud console to accept the fair use policy.
rate_limited429Wait for the Retry-After header or retryAfterSeconds, then retry.

ZevAuth’s Errors page covers errors from connecting, tokens and refresh.

Rate limits

Limits apply per app:

  • 120 requests a minute
  • 10 deploys a minute

Over the limit, calls return 429 rate_limited with a Retry-After header and retryAfterSeconds in the body. See also ZevAuth’s Rate limits.

Attribution

Everything your app does is recorded with your app and the person it acts for.

  • People see “Deployed by <your app>” on deployments your app starts.
  • Team owners and admins see connected apps in their team settings.
  • People manage and disconnect apps on the ZevID account site.

When a person disconnects, your calls start failing with grant_revoked. ZevAuth can also tell you through webhooks. See Revocation.

Testing

Test versions of your app use ZevAuth test environments.

  • A test version connects only to the ZevCloud teams of people on your own team.
  • Calls work the same as for a live app, except that a test version can only create free services. A paid plan or database tier returns 400 paid_plans_live_only.
  • Test connections end on their own. After that, calls fail with grant_expired (ZevAuth calls it test_grant_expired) and you connect again.

See Test environments.

Updated at, Monday, October 26, 2026