Files

Girish Ramakrishnan fb4d6f7649 doc: fix dns config api docs

2016-10-09 00:24:30 -07:00

42 KiB

Raw Blame History

Overview

The Cloudron provides a RESTful API to manage all aspects of the Cloudron like adding users, configuring groups and installing apps.

If you are an app developer, the Cloudron CLI tool implements a workflow that allows you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.

API Origin

The Cloudron API is available at the my subdomain of your Cloudron.

For example, if the Cloudron is on a custom domain, then this would be https://my.customdomain.com. If the Cloudron is on a cloudron.me subdomain, then this would be https://my-demo.cloudron.me.

Authentication

Getting API Tokens

POST /api/v1/developer/login admin

Creates a token given user credentials.

Request:

{
    username: <string>,
    password: <string>
}

Set username to your username and password to your password. Currently, only Cloudron administrators can create API tokens.

Response (200):

{
    token: <string>,        // Token used for accessing the API
    expiresAt: <date>       // ISO-8601 UTC date the token expires
}

Curl example:

curl -X POST -H "Content-Type: application/json" -d '{"username": "cloudron", "password":"cloudron"}' https://my-demo.cloudron.me/api/v1/developer/login

Using API tokens

The access token can either be provided via the request query ?access_token=<token>.

curl -H "Content-Type: application/json" https://$CLOUDRON_ORIGIN/api/v1/users?access_token=$TOKEN

Alternately, the token can be provided via the Authorization header using Bearer <token>.

curl -H "Content-Type: application/json" -H "Authorization: Bearer <token>" https://$CLOUDRON_ORIGIN/api/v1/users

OAuth

OAuth authentication is meant to be used by apps. An app can get an OAuth token using the oauth or simpleauth addon.

Tokens obtained via OAuth have a restricted scope wherein they can only access the user's profile. This restriction is so that apps cannot make undesired changes to the user's Cloudron.

The access token can be provided either via the request query ?access_token=<token> or in the Authorization header using Bearer <token>.

REST

Requests

All requests must be made via https protocol to ensure that the connection is encrypted.

The general idea behind HTTP methods is:

Use GET to retrieve resource information
Use DELETE to destroy a resource
Use PUT to update an existing resource
Use POST to create a new resource

Error

Error response objects have a status field indicating the HTTP error and a message field containing a detailed description of the error.

Pagination

APIs that list objects take a page query parameters to indicate the page number starting from index 1. The per_page query parameter can be used to specify the number of items to be returned.

Endpoints

Apps

Install app

POST /api/v1/apps/install admin

Request:

{
    location: <string>,              // required: the subdomain on which to install the app
    appStoreId: <string>[@<semver>], // required: Cloudron Store Id of the app. Alternately, provide a manifest
    manifest: <manifest>,            // manifest of the app to install. required if appStoreId is unset.
    portBindings: null || {          // mapping from application ports to public ports
    },
    accessRestriction: null || {     // required. list of users and groups who can access this application
        users: [ ],
        groups: [ ]
    },
    icon: <string>,                  // icon as base64 encoded string
    cert: <string>,                  // pem encoded TLS cert
    key: <string>,                   // pem encoded TLS key
    memoryLimit: <number>,           // memory constraint in bytes
    altDomain: <string>,             // alternate domain from which this app can be reached
    xFrameOptions: <string>          // set X-Frame-Options header, to control which websites can embed this app
}

appStoreId is the Cloudron Store Id of this application. For example, io.gogs.cloudronapp is the id of Gogs app. A specific version can be specified using the '@' suffix. For apps that are not published on the Cloudron Store, skip this field and provide a manifest instead. Apps with an appStoreId will automatically be kept up-to-date as newer version of the app are published on the store.

manifest is the manifest of the app to be installed. This is only required if appStoreId is not provided. Apps with a manifest won't receive automatic updates.

location is the subdomain on which the app is installed. This can be empty if the app was installed on the naked domain. If another app already exists in the same location, 409 is returned.

For apps that require login, accessRestriction is the restricted list of users and groups that can access this app. If null, any user of this Cloudron can access this app. Note that the accessRestriction field only works if the app is integrated with Cloudron Authentication.

icon is an application icon that is displayed in the web ui. If not provided, this is automatically downloaded from the Cloudron Store (or uses a fallback icon).

cert and key provide the TLS certificates. If the domain name of the app does not must match with the certificate provided, a 400 will be returned.

If altDomain is set, the app can be accessed from https://<altDomain>.

xFrameOptions can hold one of the following values:

DENY - to prevent embedding from any website
SAMEORIGIN - allows embedding from the same domain as the app. This is the default.
ALLOW-FROM https://example.com/ - allows this app to be embedded from example.com

Get app

GET /api/v1/apps/:appId admin

Gets information about the app with id appId.

Response (200):

{
    id: <string>,                    // a unique id for the app
    appStoreId: <string>,            // Cloudron Store Id for updates
    manifest: <manifest>,            // current manifest of the app
    installationState: <enum>,       // See below
    installationProgress: <string>,  // friendly string indicating installation progress
    runState: <enum>,                // see below
    health: <enum>,                  // health of the application
    location: <string>,              // subdomain on which app is installed
    fqdn: <string>,                  // the FQDN of this app
    altDomain: <string>              // alternate domain from which this app can be reached
    accessRestriction: null || {     // list of users and groups who can access this application
        users: [ ],
        groups: [ ]
    },
    lastBackupId: <string>,          // last known backup of this app
    manifest: <manifest>,            // the application manifest
    portBindings: {                  // mapping from application ports to public ports
    },
    iconUrl: <url>,                  // a relative url providing the icon
    memoryLimit: <number>            // memory constraint in bytes
}

id is an unique id for this application.

appStoreId is the Cloudron Store id of this application. Cloudron will use this id to look for updates to this application. This can be null if none was provided at installation time.

manifest is the Cloudron Manifest of the app.

installationState is one of the values below:

pending_install - The app is being installed. Use the installationProgress field to track the progress.
pending_configure - The app is being re-configured. For example, if the app was moved to a new location or the port bindings was changed.
pending_uinstall - The app is being uninstalled.
pending_restore - The app is being restored from a previous backup.
pending_update - The app is being updated.
pending_force_update - The app is being force-updated.
pending_backup - The app is being backed up.
error - There was an error executing one of the above pending commands.
installed - The app is installed. Use the runState and health to determine if the app is running and healthy.

installationProgress is a string indicating the progress when the app's installationState is one of the pending_* states. It is of the format <percent>, <message>.

runState is one of the values below:

pending_start - The app is being started.
pending_stop - The app is being stopped.
stopped - The app was stopped.
running - The app is running.

health is one of the values below:

healthy - The app is responding to health checks and is healthy.
unhealthy - The app is not responding to health checks.
error - There was an error checking the health of the app.
dead - The app is dead. Most likely it was stopped or being uninstalled.

location is the subdomain on which the app is installed. This can be empty if the app was installed on the naked domain. The app can be accessed from fqdn i.e https//<fqdn>. If altDomain is set, the app should be accessed from https://<altDomain>.

lastBackupId is the last valid backup id. The restore API can be used to restore the app to this backup.

manifest is the application manifest.

List apps

GET /api/v1/apps/:appId admin

Gets the list of installed apps.

Response (200):

{
    apps: [
        {
            id: <string>,                    // a unique id for the app
            appStoreId: <string>,            // Cloudron Store Id for updates
            manifest: <manifest>,            // current manifest of the app
            installationState: <enum>,       // See below
            installationProgress: <string>,  // friendly string indicating installation progress
            runState: <enum>,                // see below
            health: <enum>,                  // health of the application
            location: <string>,              // subdomain on which app is installed
            fqdn: <string>,                  // the FQDN of this app
            altDomain: <string>              // alternate domain from which this app can be reached
            accessRestriction: null || {     // list of users and groups who can access this application
                users: [ ],
                groups: [ ]
            },
            lastBackupId: <string>,          // last known backup of this app
            manifest: <manifest>,            // the application manifest
            portBindings: {                  // mapping for application ports to public ports
            },
            iconUrl: <url>,                  // a relative url providing the icon
            memoryLimit: <number>            // memory constraint in bytes
        },
        ...
    ]
}

Get icon

GET /api/v1/apps/:appId/icon admin

Gets the icon of the application with id appId as image/png.

The icon is used in the display at Cloudron admin UI.

Backup app

POST /api/v1/apps/:appId/backup admin

Starts a backup of the application with id appId.

The backup progress can be tracked by polling the value of installationProgress.

List app backups

GET /api/v1/apps/:appId/backups admin

Gets the backups of the application with id appId.

Use the Backup API to download the backup. Use the Clone API to create another instance of this app from a backup.

Response (200):

{
    backups: [
        {
            id: <string>,                   // a unique id for this backup
            creationTime: <date>,           // ISO-8601 date in UTC
            version: <semver>,              // the app version
            type: <string>,                 // 'app'
            dependsOn: [ <string>, ... ],   // always an empty array for app backups
            state: <string>                 // 'normal'
        },
        ...
    ]
}

Restore app

POST /api/v1/apps/:appId/restore admin

Restores the app from a backup.

Request:

{
    backupId: null || <string>
}

backupId is an id from the list app backups API.

Note that app backups are tied to the app's version (see the version field of the backup). So, restoring an app may result in reverting the app to a previous version.

Setting backupId to null has the same effect as reinstalling the application.

Clone app

POST /api/v1/apps/:appId/clone admin

Clones the app from a backup.

Request:

{
    backupId: <string>,            // required. the cloned app will start with this data.
    location: <string>,            // required. the subdomain for the cloned app
    portBindings: null || {        // required. mapping from application ports to public ports
    }
}

backupId is an id from the list app backups API.

location is a subdomain for the cloned app and will result in a 409 in case of a conflict.

portBindings is a list of new tcp port mappings for the cloned app.

Response(201):

    {
        id: <string>                // app id of the new app
    }

The clone progress can be tracked by polling the value of installationProgress. Be sure to use the id of the new app returned above and not the original app's id.

Get logs

GET /api/v1/apps/:appId/logs admin

Get the logs of an application with id appId.

The lines query parameter can be used to specify the number of log lines to download.

The response has Content-Type set to 'application/x-logs' and Content-Disposition set to attachment; filename="log.txt.

Response(200):

Line delimited JSON.

    {
        realtimeTimestamp: <number>,          // wallclock timestamp
        monotonicTimestamp: <number>,         // time passed since boot
        message: [ <byte>,... ],              // utf8 buffer
        source: <process name>                // source of this message
    }

Logs are aggregated from one or more sources. The application logs have the source set to main. Other sources include scheduler.

Get log stream

GET /api/v1/apps/:appId/logstream admin

Stream the logs of an application with id appId as a text/event-stream. See the EventSource interface documentation for details.

The lines query parameter can be used to specify the number of log lines to prefetch.

Response(200):

Line delimited JSON

    {
        realtimeTimestamp: <number>,          // wallclock timestamp
        monotonicTimestamp: <number>,         // time passed since boot
        message: [ <byte>,... ],              // utf8 buffer
        source: <process name>                // source of this message
    }

Logs are aggregated from one or more sources. The application logs have the source set to main. Other sources include scheduler.

Configure app

POST /api/v1/apps/:appId/configure admin

Re-configures an existing app with id appId.

Configuring an app won't preserve existing data. Cloudron apps are written in a way to support reconfiguring any of the parameters listed below without loss of data.

Request:

    location: <string>,            // the subdomain on which to install the app
    portBindings: null || {        // mapping from application ports to public ports
    },
    accessRestriction: null || {   // required. list of users and groups who can access this application
        users: [ ],
        groups: [ ]
    },
    icon: <string>,                 // icon as base64 encoded string
    cert: <string>,                 // pem encoded TLS cert
    key: <string>,                  // pem encoded TLS key
    memoryLimit: <number>,          // memory constraint in bytes
    altDomain: <string>,            // alternate domain from which this app can be reached
    xFrameOptions: <string>         // set X-Frame-Options header, to control which websites can embed this app

All values are optional. See Install app API for field descriptions.

Update app

POST /api/v1/apps/:appId/update admin

Updates an app with id appId.

Updating an app updrades (or downgrades) the app preserving existing data. To be safe, the update process makes a backup of existing app data first before updating the app. This allow you to restore the app should the upgrade fail.

Only apps that are installed, running and responding to health checks can generate a consistent back up. For this reason, it is not possible to update apps that are in any other state. To override this, use the force parameter described below.

Request:

{
    appStoreId: <string>[@<semver>], // the new version of the app
    manifest: <manifest>,            // the manifest of the app
    portBindings: {                  // optional
    },
    icon: <string>,                  // optional
    force: <boolean>                 // optional. default: false
}

appStoreId is the id of the app to install from the Cloudron Store. The API does not verify that the version provided here is greater than the existing app version allowing you to downgrade apps. Downgrading should be used with extreme care because the older version of the app may not understand the format of existing data (for example, new db schema may not be understod by the older version).

manifest provides information of the new app version that the app needs to be updated to. This is only required if appStoreId was not provided at installation time.

If the new version of the app requires new ports to be allocated for the app, then mapping for the new ports can be provided in portBindings.

icon specifies any new icon as a base64 encoded string for the updated version of the app.

The Cloudron will only update apps that are installed, running and responding to health checks. Before each update, the app is backed up so that it may be restored easily in case of a bad update.

force can be used to force an update even if the app is in a state which prevents an update. This is useful during app development, where you can force a crashed app to update to the latest code.

The update progress can be tracked by polling the value of installationProgress.

Curl example to update Gogs to a new version 0.13.0:

curl -X POST -d '{ "appStoreId": "io.gogs.cloudronapp@0.13.0" }' -H 'Content-Type: application/json' -H 'Authorization: Bearer 256e4c6c6f783dbff95ae233c63a36e297ef70a3528171b891a399f895a8e0e0' https://my-demo.cloudron.me/api/v1/apps/aaa8ad53-301b-4a77-9551-5df261686166/update

Exec

GET /api/v1/apps/:appId/exec admin

Executes an arbitrary command in the context of the app.

Query Parameters:

cmd: JSON encoded string array of the command to execute. default: '/bin/bash'
rows: optional. the tty window row size
columns: optional. the tty window column size
tty: set to true if a tty should be allocated

In order to provide separate streams for stdout and stderr, the http connection is upgraded to tcp using the following headers:

Upgrade: tcp
Connection: Upgrade

Once upgraded, the connection provides a full-duplex tcp connection. Clients can write stdin to the connection. If a tty was allocated, then the server provides stdout and stderr as a single stream. If no tty was allocated, then the server writes data in the following format:

<stream type> <size> <payload>

See the Docker docs for details.

Curl example to execute 'ls' command:

curl -H 'Upgrade: tcp' -H 'Connection: Upgrade' -H 'Authorization: Bearer eba011a45eb056c7497820c408d1170e94ac7ed0fb10cef798fcdaacbcbcd2ee' 'https://my-demo.cloudron.me/api/v1/apps/41dfe1f1-edb3-4011-9ba3-889d0b24a177/exec?cmd=%5B%22ls%22%5D&tty=true'

Start app

POST /api/v1/apps/:appId/start admin

Starts an app.

If the app cannot be started, the response code is 409. This can happen if the app is in a state where it cannot started (for example, it is still installing).

Stop app

POST /api/v1/apps/:appId/stop admin

Stops an app.

If the app cannot be stopped, the response code is 409. This can happen if the app is in a state where it cannot stopped (for example, it is installing).

When an app is stopped, the app's location will show an error page indicating that the app is not running.

Uninstall app

POST /api/v1/apps/:appId/uninstall admin

Uninstalls an app.

The existing backups of the app are still preserved (as per the backup configuration) and the backup can be used to restore the app to the same state later.

Backups

Create a backup

POST /api/v1/backups admin

Schedules a complete backup of the Cloudron.

Use the Progress API to track the progress of the backup.

List backups

GET /api/v1/backups admin

Lists the existing box backups.

The Cloudron has two types of backups:

app backups - Each app is backed up individually. This approach allows one to restore each app independently of other apps. Use the app backup API, if you want to list the backups of a specific app.
box backups - The Cloudron backs up certificates, user information, settings separately. This backup contains a (virtual) link to all the app backups .

Response (200):

{
    backups: [
        {
            id: <string>,                   // a unique id for this backup
            creationTime: <date>,           // ISO-8601 date in UTC
            version: <semver>,              // the Cloudron version when this backup was created
            type: <string>,                 // `box`
            dependsOn: [ <string>, ... ],   // list of app backups that are part of this box backup
            state: <string>                 // 'normal'
        },
        ...
    ]
}

Download backup

POST /api/v1/backups/:backupId/download_url admin

Generates a temporary URL to download the backup with id backupId.

All backups are encrypted and tar zipped. backupKey returned in the response can be used to decrypt the backup.

Response (200):

{
    id: <string>,
    url: <url>,                      // download backups from this url
    backupKey: <string>              // key to use to decrypt the backup
}

Curl example to download, decrypt and extract backup to current directory:

curl -L <url> | openssl aes-256-cbc -d -pass "pass:$<backupKey>" | tar -zxf -

Cloudron

Update the Cloudron

POST /api/v1/cloudron/update admin

Updates the Cloudron to the latest version.

If no new version is available, the response code will be 422.

Some actions and events on the Cloudron like backups, app installs may block the Cloudron from updating. In such a case, the response code will be 409.

If the update request was accepted, the response code will be 202. Use the Progress API to track the progress of the update.

Reboot the Cloudron

POST /api/v1/cloudron/reboot admin

Reboots the Cloudron.

Get progress

GET /api/v1/cloudron/progress public

Gets information about an in-progress Cloudron update or backup.

update or backup is null when there is no such activity in progress.

Response (200):
{
    update: null || { percent: <number>, message: <string> },
    backup: null || { percent: <number>, message: <string> }
}

Get status

GET /api/v1/cloudron/status public

Gets information about the Cloudron state and how it got provisioned.

Response (200):
{
    activated: <boolean>,
    version: <semver>,
    boxVersionsUrl: <url>,     // Location of the Cloudron versions file to check for updates
    apiServerOrigin: <url>,    // Always https://api.cloudron.io
    provider: <string>,
    cloudronName: <string>
}

Get avatar

GET /api/v1/cloudron/avatar public

Returns the Cloudron avatar image as Content-Type: image/png.

Response (200):

Content-Type: image/png

Get configuration

GET /api/v1/cloudron/config admin

Gets information on how the Cloudron is configured. This is similar to the Status API except this contains some sensitive information and is not public.

Response (200):
{
    apiServerOrigin: <string>,        // Always https://api.cloudron.io
    webServerOrigin: <string>,        // Always https://cloudron.io
    isDev: <boolean>,                 // internal
    fqdn: <fqdn>,                     // The FQDN
    ip: <ip>,                         // The public IP
    version: <semver>,                // Current version
    update: {
        box: <semver>,                // Set to the next available Cloudron version
        apps: {
            <appid>: <semver>.        // Set to next available app version
            ...
        }
    },
    progress: {                       // See progress API
    },
    isCustomDomain: <boolean>,        // false if the cloudron is on a .cloudron.me subdomain. true otherwise
    developerMode: <boolean>,
    region: <string>,                 // the geo-region of this Cloudron
    size: <string>,                   // the size of this Cloudron
    billing: <boolean>,               // true if the user has setup billing
    memory: <string>,                 // the physical memory
    provider: <string>,
    cloudronName: <string>            // the name of this cloudron
}

Eventlog

List events

GET /api/v1/eventlog admin

Lists all the past events.

The action query parameter can be used to list events of a specific action.

The search query parameter can be used to do a wildcard ('search') on the data field.

This API supports pagination - use the page and per_page query parameters to get specific pages.

Response (200):

{
    eventlogs: [
        {
            id: <string>,            // unique id for the event
            action: <enum>,          // see below
            source: <object>,        // originator of this event
            data: <object>,          // value depends on action. see below
            creationTime: <date>     // ISO-8601 date in UTC
        },
        ....
    ]
}

action is one of the values below:

cloudron.activate
app.configure
app.install
app.restore
app.uninstall
app.update
backup.finish
backup.start
certificate.renew
settings.climode
cloudron.start
cloudron.update
user.add
user.login
user.remove
user.update

source contains information on the originator of the action. For example, for user.login, this contains the IP address, the appId and the authType (ldap or simpleauth or oauth).

data contains information on the event itself. For example, for user.login, this contains the userId that logged in. For app.install, it contains the manifest and location of the app that was installed.

To list all the app installation events:

curl -X GET -H 'Authorization: Bearer cb0463455a6606482be7956fc3abd53330ae23244e3492cda3914a2c5154c47e' https://my-demo.cloudron.me/api/v1/eventlog?action=app.install

Groups

Cloudron groups are a mechanism to restrict application access to a subset of users. You can add one or more users to a group and assign one or more groups to an application. Only users that are members of any of the groups can access the application.

Group membership is dynamic. Users instantly lose or gain access to an application based on their group membership.

Create group

POST /api/v1/groups admin

Creates a new group.

Request:

{
    name: <string>
}

name must be atleast 2 characters. The special built-in group named admin has all the Cloudron administrators.

Response (200):

{
    id: <string>,
    name: <string>
}

Get group

GET /api/v1/groups/:groupId admin

Gets an existing group with id groupId.

Response (200):

{
    id: <string>,
    name: <string>,
    userIds: [ <string>, ... ]  // list of users that are part of this group
}

Set members

PUT /api/v1/groups/:groupId/members admin

Sets the members of an existing group with id groupId. Note that this replaces the existing users with the provided userIds.

Request:

{
    userIds: [ <string>, ... ] // list of users to be part of this group
}

List groups

GET /api/v1/groups admin

Lists all groups.

Response (200):

{
    groups: [
        {
            id: <string>,
            name: <string>,
            userIds: [ <string>, ... ]  // list of users that are part of this group
        },
        ...
    ]
}

Delete group

DELETE /api/v1/groups/:groupId admin

Deletes an existing group with id groupId.

The special admin group cannot be removed.

Response (204):

{}

Profile

Get profile

GET /api/v1/profile profile

Gets the profile information of the token owner. This is useful to verify access tokens.

Response (200):

{
    id: <string>,
    username: <string>,
    email: <email>,
    admin: <boolean>,
    displayName: <string>
}

Update profile

POST /api/v1/profile profile

Updates the email or displayName of the token owner.

Request:

{
    email: <email>,         // optional
    displayName: <string>   // optional
}

Response (204):

{}

Update password

POST /api/v1/profile/password profile

Updates the password of the token owner.

Request:

{
    password: <string>,     // current password. only required for OAuth tokens
    newPassword: <string>
}

Response (204):

{}

Tutorial

POST /api/v1/profile/tutorial profile

Toggles display of the tutorial when the token owner logs in.

Request:

{
    showTutorial: <boolean>
}

Response (204):

{}

Settings

Get auto update pattern

GET /api/v1/settings/autoupdate_pattern admin

Gets the auto update pattern that the Cloudron uses to automatically update itself and installed apps.

Patterns are matched based on the Cloudron's timezone.

Response (200):

{
    pattern: <string>            // a cron pattern
}

Set auto update pattern

POST /api/v1/settings/autoupdate_pattern admin

Sets the auto update pattern that the Cloudron uses to automatically update itself and installed apps.

Request:

{
    pattern: <string>     // a cron pattern
}

pattern has the format listed in the node-cron page. Note that unlike classic crontab format, the pattern contains seconds as the first part.

Setting pattern to never disables auto update.

Some examples of patterns are:

00 00 1,3,5,23 * * * would run updates at 1am, 3am, 5am, 11pm every night.
0 030 4 1,15 * 5 would run updates at 4:30 am on the 1st and 15th of each month, plus every Friday.

Patterns are matched based on the Cloudron's timezone.

Get avatar

GET /api/v1/settings/cloudron_avatar admin

Gets the Cloudron avatar image as Content-Type: image/png.

Note that the avatar is also available without authentication using the Get avatar API.

Response (200):

Content-Type: image/png

Set avatar

POST /api/v1/settings/cloudron_avatar admin

Sets the avatar of the Cloudron.

The request is sent as multipart/form-data. It must contain a field named avatar and must be a png.

Example:

curl -X POST -F "avatar=@./avatar.png"  -H 'Authorization: Bearer 215841b5943f5432a26ef3a1526f548a40268a92ed9baca5db980be0545da596'  https://my-demo.cloudron.me/api/v1/settings/cloudron_avatar

Get Backup Configuration

GET /api/v1/settings/backup_config admin internal

Gets the credentials used to upload backups.

This is currently internal API and is documented here for completeness.

Response(200):

{
  "provider": <string>,  // 'caas'
  "key": <string>,       // encryption key
  "region": <string>,    // s3 region
  "bucket": <string>,    // s3 bucket name
  "prefix": <string>,    // s3 bucket prefix
  "token": <string>      // caas specific token
}

Set Backup Configuration

POST /api/v1/settings/backup_config admin internal

Sets the credentials used to upload backups.

This is currently internal API and is documented here for completeness.

Get DNS Configuration

GET /api/v1/settings/dns_config admin internal

Gets the credentials used to configure DNS.

This is currently internal API and is documented here for completeness.

Response(200):

{
  "provider": <string>  // 'caas' or 'route53' or 'digitalocean'
}

Set DNS Configuration

POST /api/v1/settings/dns_config admin internal

Sets the credentials used to configure DNS.

This is currently internal API and is documented here for completeness.

Get Email Configuration

GET /api/v1/settings/mail_config admin internal

Gets the email configuration. The Cloudron has a built-in email server for users. This configuration can be used to disable the server. Note that the Cloudron will always be able to send email on behalf of apps, regardless of this setting.

Response(200):

{
  "enabled": <boolean> // true to enable email
}

Set Email Configuration

POST /api/v1/settings/mail_config admin internal

Sets the email configuration. The Cloudron has a built-in email server for users. This configuration can be used to enable or disable the email server. Note that the Cloudron will always be able to send email on behalf of apps, regardless of this setting.

Request:

{
    "enabled": <boolean>
}

Set fallback Certificate

POST /api/v1/settings/certificate admin internal

Sets the fallback TLS certificate to use if automatic certificate generation or renewal fails.

The fallback certificate only applies to Cloudrons running on a custom domain.

The Cloudron automatically installs and renews certificates for all subdomains using Let's Encrypt. The fallback certificate is used if Let's Encrypt fails.

Request:

{
    cert: <pem encoded string>,   // TLS certificate including the full chain
    key:  <pem encoded string>    // TLS key
}

Get name

GET /api/v1/settings/cloudron_name admin

Gets the name of the Cloudron.

Note that the name is also available without authentication using the Get status API.

Response (200):
{
    name: <string>
}

Set name

POST /api/v1/settings/cloudron_name admin

Sets the name of the Cloudron.

The Cloudron name is shown in the title bar and all the login screens. It has a maximum length of 32 characters.

Request:

{
    name: <string>
}

Get timezone

GET /api/v1/settings/time_zone admin

Gets the timezone of the Cloudron.

Timezone is automatically set based on the IP address from where the Cloudron was activated. This timezone is used with the auto update pattern to trigger updates at the correct time.

Response (200):
{
    timeZone: <string>          // the timezone
}

Set timezone

POST /api/v1/settings/time_zone admin

Sets the time zone of the Cloudron.

Timezone is automatically set based on the IP address from where the Cloudron was activated. This timezone is used with the auto update pattern to trigger updates at the correct time.

See the Tz database for a list of valid values.

Request:

{
    timeZone: <string>
}

Users

Create user

POST /api/v1/users admin

Creates a new user.

Request:

{
    email: <email>,         // required
    invite: <boolean>,      // required
    username: <string>,     // optional
    displayName: <string>   // optional
}

invite indicates if the user should be sent an invitation email. The invitation email allows the user to setup a username and password. Set this to false to send out a custom invitation email of your own to the user. The invitation link can be constructed based on the resetToken in the response.

username has to be at least two characters long and must be alphanumeric. If unspecified, the new user can pick any available name on first sign up. For security, username cannot be changed once set. Some apps (incorrectly) use the username as their unique identifier. As a result, it might mistake a newly created user as a previous user with the same username. If you want to reset the username, delete the existing the user and create a new one again.

displayName may consist of one or more words to specify the first name and surname.

Response (201):

{
    id: <string>,
    username: <string>,
    displayName: <string>,
    email: <email>,
    groupIds: [ <string>, ... ]
    resetToken: <string>    // User can sign up at https://my-demo.cloudron.me/api/v1/session/account/setup.html?reset_token=<resetToken>
}

Get user

GET /api/v1/users/:userId admin

Gets detailed information about a specific user with id userId.

Response (200):

{
    id: <string>,
    username: <string>,
    email: <email>,
    groupIds: [ <string>, ... ],   // list of groups this user is part of
    admin: <boolean>,              // a boolean indicating if this user is an admin
    displayName: <string>
}

List users

GET /api/v1/users admin

Lists all users.

Response (200):

{
    users: [
        {
            id: <string>,
            username: <string>,
            email: <email>,
            displayName: <string>,
            groupIds: [ <string>, ... ],   // list of groups this user is part of
            admin: <boolean>               // a boolean indicating if this user is an admin
        },
        ...
    ]
}

Update user

POST /api/v1/users/:userId admin

Modify user's email or display name. As noted in Create user, username cannot be changed.

Request:

{
    email: <email>,              // optional
    displayName: <displayName>   // optional
}

Response (204):

{}

Re-invite user

POST /api/v1/users/:userId/invite admin

Resends the invitation link to an existing user.

A re-invite call invalidates any previous invite links. The invitation link can be constructed based on the resetToken in the response.

Request:

{}

Response (200):

{
    resetToken: <string>   // // User can sign up at https://my-demo.cloudron.me/api/v1/session/account/setup.html?reset_token=<resetToken>
}

Set groups

PUT /api/v1/users/:userId/groups admin

Sets the groups for the user with id userId.

Groups are identified by groupIds which can be retrieved using the Groups API.

An admin cannot remove himself from the special admin group. This will result in a response code of 403.

Note that this call will replace the current groups for this user, it does not merge the provided ones with the current groups for that user.

Request:

{
    groupIds: [ <string>, ... ]
}

Response (204):

{}

Delete user

DELETE /api/v1/users/:userId admin

Deletes user with id userId.

A user cannot remove himself, this will result in a response code of 403.

A deleted user will not be able to login to any app anymore. Currently, apps are not notified of a user deletion and any user-specific data data will persist on the app.

Note that applications may cache user credentials (for example, as a browser session cookie) and thus the effect of a deletion may not be immediately visible until the user logs out.

Response (204):

{}

42 KiB Raw Blame History

Overview

API Origin

Authentication

Getting API Tokens

Using API tokens

OAuth

REST

Requests

Error

Pagination

Endpoints

Apps

Install app

Get app

List apps

Get icon

Backup app

List app backups

Restore app

Clone app

Get logs

Get log stream

Configure app

Update app

Exec

Start app

Stop app

Uninstall app

Backups

Create a backup

List backups

Download backup

Cloudron

Update the Cloudron

Reboot the Cloudron

Get progress

Get status

Get avatar

Get configuration

Eventlog

List events

Groups

Create group

Get group

Set members

List groups

Delete group

Profile

Get profile

Update profile

Update password

Tutorial

Settings

Get auto update pattern

Set auto update pattern

Get avatar

Set avatar

Get Backup Configuration

Set Backup Configuration

Get DNS Configuration

Set DNS Configuration

Get Email Configuration

Set Email Configuration

Set fallback Certificate

Get name

Set name

Get timezone

Set timezone

Users

Create user

Get user

List users

Update user

Re-invite user

Set groups

Delete user

42 KiB

Raw Blame History