Dokümanlar /
... / Managing Applications / API Access

🔑 API Access

An application can drive ODAC itself (list apps, send mail, add a domain) by calling the same API the CLI uses. odac app api decides whether an app may do that, and which actions it may call. Nothing is granted by default: an app with no grant has neither a key nor a socket to reach.

Scope: This Server Only

[!IMPORTANT]
This API is local. It talks to the ODAC server running on this machine and nothing else. It never connects to ODAC Cloud, and it carries no notion of your other servers. An app you grant access to can manage this server's apps, domains and mailboxes; it cannot reach or manage any other server registered in ODAC Cloud.

The key follows from that: ODAC_API_KEY is minted by your local ODAC server, signed with a secret it generated for itself on first start, and injected into the container automatically. There is no ODAC Cloud account, login, or connection involved. This works exactly the same on a machine that has never talked to the Cloud, and on one that is fully offline.

How an App Reaches the API

When an app has a grant, ODAC injects two things at container start:

Variable Value What it is
ODAC_API_SOCKET /odac/api.sock The API's unix socket. ODAC's run directory is bind-mounted read-only at /odac.
ODAC_API_KEY signed token Identifies the calling app on every request.

The socket is a local file, not a network service, so this works for apps that are isolated with no outbound access at all, and for apps on the shared bridge or in host network mode alike.

A request is one JSON object written to the socket:

{ "auth": "<ODAC_API_KEY>", "action": "app.list", "data": [] }

Write the whole request as soon as the connection opens. A connection must deliver a complete request within 10 seconds and at most 4 MiB (ODAC_API_MAX_REQUEST_BYTES on the server raises the size); past either limit it is closed, and an oversized one is answered with request_too_large first. Both limits cover everything sent before an action starts, failed attempts included. Once the action runs, it has as long as it needs.

Action names are the ones in the CLI Reference with the space replaced by a dot: odac app list is app.list, odac mail send is mail.send.

Available Actions

These are the actions available to applications. An app may call the ones you granted it, and --all covers the whole table.

Action data What it does
app.list [] or [true] for detail List apps
app.create [config] Create an app (same object the CLI builds). Volumes are limited, see below
app.delete [app], or [app, {"purge": false}] to keep its data Delete an app
app.start [app] Start a stopped app
app.stop [app] Stop a running app
app.restart [app] Restart an app
app.isolate [app, true|false] Cut off or restore outbound access
app.gpu [app, {"runtime": "nvidia"}], or [app, false] to release Reserve host GPUs for an app
app.device.delete [app, hostPath] Disconnect a host device
domain.list [], or [app] to filter List domains
domain.add [domain, app] Route a domain to an app. See below
domain.delete [domain] Remove a domain. See below
dns.list [domain] List a domain's DNS records
ssl.renew [domain] Force an SSL certificate renewal
mail.send [message] Send mail from one of your domains
mail.list [domain] List mailboxes
mail.create [email, password, passwordAgain] Create a mailbox
mail.password [email, password, passwordAgain] Change a mailbox password
mail.delete [email] Delete a mailbox
domain.mtls.cert.issue [domain, {"csr", "name", "hosts", "days"?, "renews"?}] Sign a client certificate for the app's own hosts. See below
domain.mtls.cert.revoke [fingerprint] Revoke one of the app's client certificates
domain.mtls.cert.list [], or [domain] to filter List the app's client certificates
domain.mtls.cert.import [{"cert", "hosts", "name"?}] Record a certificate another server signed with a shared CA

app is an App ID or name, exactly like the CLI's -i argument.

An app can never take a client certificate policy off a host, whatever it was granted, because domain.mtls.set is closed to apps. Three calls are refused to it for that reason, and only the server operator can make them: domain.delete on a domain that has a policy (or on one of its subdomains), domain.add of a domain at or below another app's domain that has a policy, and app.delete of an app that has a domain with a policy.

mail.send is the one action whose argument is a message object rather than plain strings. from and to use the parsed-mail address shape, a value list of { "address": ... } objects, and only the first entry of each is used:

{
  "auth": "<ODAC_API_KEY>",
  "action": "mail.send",
  "data": [{
    "from": { "value": [{ "address": "no-reply@example.com" }] },
    "to": { "value": [{ "address": "someone@example.com" }] },
    "subject": "Welcome",
    "header": { "Content-Type": "text/html; charset=utf-8" },
    "html": "<p>Hello</p>",
    "text": "Hello"
  }]
}

from must belong to a domain routed to the calling app, or to a subdomain of one. A domain of another app is answered as Domain ... not found., exactly like a domain the server does not have, because the message would go out DKIM-signed as that domain. header is required; supply at least a Content-Type, and provide html, text, or both. Header names must be plain field names and no value may contain a line break; such a message is refused. From, To, Subject and MIME-Version are added when header does not name them.

A true result means the message is queued, not that it reached the recipient. ODAC keeps retrying a temporary refusal (greylisting, a busy server) for five days, or for ODAC_MAIL_QUEUE_HOURS when that is set on the server. When the recipient's server refuses the message for good, or the time runs out, the sender gets a bounce in its INBOX if it has a mailbox on this server. An address like no-reply@ with no mailbox gets no bounce.

Creating Apps From an App

An app that creates another app gets a container confined to that new app's own directory. Every volume must be a named volume, a relative path such as data or db/files that ODAC places under the new app's directory. The create is refused when a volume:

  • is an absolute host path (/, /var/run/docker.sock), or climbs out with ..,
  • sits inside another of the same app's volumes, or contains the directory that holds its config files,
  • passes through a symbolic link that is already on disk.

The first is the host itself. The other two would let the new container put a symbolic link where one of its own mounts resolves, which Docker follows on the next start. A recipe from the catalog is checked the same way when an app creates it. The CLI and the dashboard are not limited this way.

Connecting a host device (app.device.add) and switching an app to host networking (app.network) are never available to apps. A mapped block device is raw access to the host's disk, and the host network namespace reaches every service on the host's loopback. Both are the operator's decision, like privileged access.

Client Certificates for the App's Own Domains

The domain.mtls.cert.* actions let an app hand out client certificates for its own domains, for example to its users' devices. They are narrowed to the calling app on every request, whatever the grant says:

  • Every host must belong to a domain routed to this app. A host of another app is reported as not registered.
  • The domain must already have a client CA, which odac domain mtls set creates. An app cannot create one.
  • An app sees and revokes only certificates whose CA belongs to one of its domains and whose hosts are all its own. Anything else, including a fingerprint ODAC has no record of, answers "result": false with "data": {"code": "not_found"}.
  • Revoking a certificate that is already revoked succeeds, so a retry is safe.
  • Importing a certificate that is already recorded returns its row again. A revoked one is never imported.

Setting a mode (domain.mtls.set), changing a certificate's hosts (domain.mtls.cert.scope), and importing or removing a CA (domain.mtls.ca.import, domain.mtls.ca.remove) are never available to apps, not even with --all. Those stay with the CLI and the dashboard.

Usage

# Grant exactly what the app needs
odac app api my-app --allow app.list,mail.send

# Grant every action, present and future (asks you to confirm)
odac app api my-app --all

# Revoke
odac app api my-app --off

# Interactive: prompts for the action list
odac app api my-app

Available Prefixes

  • -i, --id: The App ID or Name
  • --allow: Comma-separated action names to permit (* means all)
  • --all: Permit every action, same as --allow "*"
  • --off: Revoke API access

Action names are validated against the server's registered actions when you grant them, so a typo is rejected at the prompt instead of turning into a permission_denied on every call the app makes.

Grant and Revoke Are Not Symmetric

⚠️ Granting takes a restart. The key and the socket mount are handed to the container when it starts, so a new grant reaches the app on its next start:

odac app restart my-app

Revoking does not. Permissions are read from the configuration on every request, so --off (or a narrowed --allow) refuses the app's very next call. The running container keeps its now-worthless key until you restart it. If you are revoking because an app misbehaved, the access is gone the moment the command returns.

Choosing Permissions

[!WARNING]
A grant is trust you place in the app's code, and the decision is yours. Apart from the client certificate guard above, a granted action reaches every app, domain and mailbox on this server, not only the app's own: an app holding app.delete can delete any app, and one holding domain.add can route any free domain to any app. Only grant access to apps whose code you know and trust, and never to an image or repository you have not reviewed.

Grant the narrowest list that works. --all still means an app can create and delete other apps, and add or remove domains and mailboxes, from inside a container with no further check. It never covers auth, update, server.stop, app.privileged, app.api, app.device.add, app.network, domain.mtls.set, domain.mtls.cert.scope, domain.mtls.ca.import or domain.mtls.ca.remove. An app that needs to send mail wants --allow mail.send. Treat a full grant the way you would treat privileged access.