# MotherDuck REST API > REST API reference for managing MotherDuck resources including databases, users, and access tokens. # MotherDuck REST API ::::warning[Preview Feature] The REST API methods are in 'Preview' and may change in the future :::: To better support scenarios that require some flexibility or dynamic configuration around managing a MotherDuck organization we are exposing an OpenAPI endpoint with some new functionality. At the moment it enables limited management of users and tokens through HTTP without requiring a DuckDB + MotherDuck client to be running. All of the methods are authenticated using a Read/Write token of a user with the `Admin` role within your MotherDuck Organization and passing it through the `Authorization` header with a value of `Bearer {TOKEN}`. ::::info[Service Account Management] You can use this REST API to programmatically manage service accounts, including their creation, token generation, and Duckling configuration. For a detailed walkthrough, see [Create and configure service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/). :::: If you would like to generate your own OpenAPI client the spec file is located at https://api.motherduck.com/docs/specs ## Error responses All endpoints return errors as JSON, with the matching HTTP status code. Validation failures (`400`) also include an `issues` array: ```json { "message": "Username must start with an alphabetic character", "code": "BAD_REQUEST", "data": { "code": "BAD_REQUEST", "httpStatus": 400, "path": "users.createServiceAccount" }, "issues": [ { "code": "invalid_string", "message": "Username must start with an alphabetic character", "path": ["username"] } ] } ``` - `message` — human-readable description of the error. - `code` — stable error code: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, or `INTERNAL_SERVER_ERROR`. - `data` — diagnostic context, including the HTTP status and an internal handler path. - `issues` — included only on `400` validation errors; one entry per field that failed validation. ## Included pages - [Create a Dive embed session for a service account](https://motherduck.com/docs/sql-reference/rest-api/dashboards-create-embed-session): Creates an embed session for the specified Dive using a service account. The username must be a service account username, not a user account. - [Create an access token for a user](https://motherduck.com/docs/sql-reference/rest-api/users-create-token): Creates an access token for a service account or for your own user account. Requires an Admin token when creating service account tokens. - [Create service account](https://motherduck.com/docs/sql-reference/rest-api/users-create-service-account): Creates a service account with a 'Member' role. This endpoint does not create user accounts. - [Delete a user](https://motherduck.com/docs/sql-reference/rest-api/users-delete): Permanently delete a user and all of their data. THIS CANNOT BE UNDONE - [Get active accounts](https://motherduck.com/docs/sql-reference/rest-api/ducklings-get-active-accounts): Get the active accounts in an organization, along with each account's running Ducklings (those in active or cooldown status). Requires 'Admin' role. - [Get user Duckling configuration](https://motherduck.com/docs/sql-reference/rest-api/ducklings-get-duckling-config-for-user): Gets Duckling (instance) configuration for a service account or user account. Requires 'Admin' role. - [Invalidate a user access token](https://motherduck.com/docs/sql-reference/rest-api/users-delete-token): Invalidates an access token for a service account or user account. Use the token ID, not the token secret. - [List a user's access tokens](https://motherduck.com/docs/sql-reference/rest-api/users-list-tokens): Lists access token metadata for a service account or user account. Token secrets are not returned. - [Set user Duckling configuration](https://motherduck.com/docs/sql-reference/rest-api/ducklings-set-duckling-config-for-user): Sets Duckling (instance) configuration for a service account or user account. Requires 'Admin' role. --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Frest-api%2Fmotherduck-rest-api%2F&page_title=MotherDuck%20REST%20API&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.