Chapter 25. superuser
Superuser API.
25.1. getConfigDump
Returns the full configuration dump of the Quay instance.
25.1.1. GET /api/v1/superuser/config
Authorizations: oauth2_implicit (super:user)
25.1.2. Responses
25.1.3. Response structure
The JSON response includes the following top-level keys:
| Name | Description | Schema |
|---|---|---|
| All config.yaml and defaulted parameters used by the Flask app that are part of the defined schema. | object | |
| Any parameters from config.yaml or defaults that are not defined in the schema. | object | |
| All environment variables available to the Flask app. | object | |
| The complete config schema (CONFIG_SCHEMA) defining expected keys and types. | object |
25.1.4. Example command
$ curl -X GET -H "Authorization: Bearer <bearer_token>"
"https://<quay-server.example.com>/api/v1/superuser/config" | jq -r .config25.2. createInstallUser
Creates a new user.
25.2.1. POST /api/v1/superuser/users/
Authorizations: oauth2_implicit (super:user)
25.2.2. Request body schema (application/json)
Data for creating a user
| Name | Description | Schema |
|---|---|---|
| username required | The username of the user being created | string |
| optional | The email address of the user being created | string |
25.2.3. Responses
25.2.4. Example command
$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{
"username": "newuser",
"email": "newuser@example.com"
}' "https://<quay-server.example.com>/api/v1/superuser/users/"25.3. changeInstallUser
Updates information about the specified user.
25.3.1. PUT /api/v1/superuser/users/{username}
Authorizations: oauth2_implicit (super:user)
25.3.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | username required | The username of the user being managed | string |
25.3.3. Request body schema (application/json)
Description of updates for a user
| Name | Description | Schema |
|---|---|---|
| password optional | The new password for the user | string |
| optional | The new e-mail address for the user | string |
| enabled optional | Whether the user is enabled | boolean |
25.3.4. Responses
25.3.5. Example command
$ curl -X PUT "https://<quay-server.example.com>/api/v1/superuser/users/<username>" \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{
"password": "<N3wP@ssw0rd!>",
"email": "<updated-email@example.com>",
"enabled": true
}'25.4. deleteInstallUser
Deletes a user.
25.4.1. DELETE /api/v1/superuser/users/{username}
Authorizations: oauth2_implicit (super:user)
25.4.2. Request body schema (application/json)
Data for deleting a user
| Name | Description | Schema |
|---|---|---|
| username required | The username of the user being deleted | string |
25.4.3. Responses
25.4.4. Example command
$ curl -X DELETE -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/{username}"25.5. listAllUsers
Returns a list of all users in the system.
25.5.1. GET /api/v1/superuser/users/
Authorizations: oauth2_implicit (super:user)
25.5.2. Query parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| query | next_page optional | The page token for the next page | string |
| query | limit optional | Limit to the number of results to return per page. Max 100. | integer |
| query | disabled optional | If false, only enabled users will be returned. | boolean |
25.5.3. Responses
25.5.4. Example command
$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"25.6. listAllLogs
List the usage logs for the current system.
25.6.1. GET /api/v1/superuser/logs
Authorizations: oauth2_implicit (super:user)
25.6.2. Query parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| query | next_page optional | The page token for the next page | string |
| query | page optional | The page number for the logs | integer |
| query | endtime optional | Latest time to which to get logs (%m/%d/%Y %Z) | string |
| query | starttime optional | Earliest time from which to get logs (%m/%d/%Y %Z) | string |
25.6.3. Responses
25.6.4. Example command
$ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/logs?starttime=<start_time>&endtime=<end_time>&page=<page_number>&next_page=<next_page_token>"25.7. listAllOrganizations
List the organizations for the current system.
25.7.1. GET /api/v1/superuser/organizations
Authorizations: oauth2_implicit (super:user)
25.7.2. Query parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | name required | The name of the organization being managed | string |
25.7.3. Responses
25.7.4. Example command
$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/organizations/"25.8. createServiceKey
Create Service Key.
25.8.1. POST /api/v1/superuser/keys
Authorizations: oauth2_implicit (super:user)
25.8.2. Request body schema (application/json)
Description of creation of a service key
| Name | Description | Schema |
|---|---|---|
| service required | The service authenticating with this key | string |
| name optional | The friendly name of a service key | string |
| metadata optional | The key/value pairs of this key’s metadata | object |
| notes optional | If specified, the extra notes for the key | string |
| expiration required | The expiration date as a unix timestamp |
25.8.3. Responses
25.8.4. Example command
$ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{
"service": "<service_name>",
"expiration": <unix_timestamp>
}' \
"<quay_server>/api/v1/superuser/keys"25.9. listServiceKeys
List Service Keys.
25.9.1. GET /api/v1/superuser/keys
Authorizations: oauth2_implicit (super:user)
25.9.2. Responses
25.9.3. Example command
$ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/keys"25.10. listAllAppTokens
Returns a list of all app specific tokens in the system.
This endpoint is for system-wide auditing by superusers and global read-only superusers.25.10.1. GET /api/v1/superuser/apptokens
Authorizations: oauth2_implicit (super:user)
25.10.2. Query parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| query | expiring optional | If true, only returns those tokens expiring soon | boolean |
25.10.3. Responses
25.10.4. Example command
Example: List all app-specific tokens
$ curl -X GET \
"https://quay-server.example.com/api/v1/superuser/apptokens" \
-H "Authorization: Bearer <superuser_access_token>" \
-H "Accept: application/json"Example: List app-specific tokens expiring soon
$ curl -X GET \
"https://quay-server.example.com/api/v1/superuser/apptokens?expiring=true" \
-H "Authorization: Bearer <superuser_access_token>" \
-H "Accept: application/json"25.11. changeUserQuotaSuperUser
Change User Quota Super User.
25.11.1. PUT /api/v1/superuser/organization/{namespace}/quota/{quota_id}
Authorizations: oauth2_implicit (super:user)
25.11.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string | |
| path | quota_id required | string |
25.11.3. Request body schema (application/json)
Description of a new organization quota
| Name | Description | Schema |
|---|---|---|
| limit_bytes optional | Number of bytes the organization is allowed | integer |
25.11.4. Responses
25.11.5. Example command
$ curl -X PUT "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota/<quota_id>" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"limit_bytes": <NEW_QUOTA_LIMIT>
}'25.12. deleteUserQuotaSuperUser
Delete User Quota Super User.
25.12.1. DELETE /api/v1/superuser/organization/{namespace}/quota/{quota_id}
Authorizations: oauth2_implicit (super:user)
25.12.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string | |
| path | quota_id required | string |
25.12.3. Responses
25.12.4. Example command
$ curl -X DELETE "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota/<quota_id>" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.13. createUserQuotaSuperUser
Create User Quota Super User.
25.13.1. POST /api/v1/superuser/organization/{namespace}/quota
Authorizations: oauth2_implicit (super:user)
25.13.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
25.13.3. Request body schema (application/json)
Description of a new organization quota
| Name | Description | Schema |
|---|---|---|
| limit_bytes required | Number of bytes the organization is allowed | integer |
25.13.4. Responses
25.13.5. Example command
$ curl -X POST "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"limit_bytes": 10737418240
}'25.14. listUserQuotaSuperUser
List User Quota Super User.
25.14.1. GET /api/v1/superuser/organization/{namespace}/quota
Authorizations: oauth2_implicit (super:user)
25.14.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
25.14.3. Responses
25.14.4. Example command
$ curl -X GET "https://quay-server.example.com/api/v1/superuser/organization/<namespace>/quota" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.15. changeOrganizationQuotaSuperUser
Change Organization Quota Super User.
25.15.1. PUT /api/v1/superuser/users/{namespace}/quota/{quota_id}
Authorizations: oauth2_implicit (super:user)
25.15.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string | |
| path | quota_id required | string |
25.15.3. Request body schema (application/json)
Description of a new organization quota
| Name | Description | Schema |
|---|---|---|
| limit_bytes optional | Number of bytes the organization is allowed | integer |
25.15.4. Responses
25.15.5. Example command
$ curl -X PUT "https://quay-server.example.com/api/v1/superuser/users/<username>/quota/<quota_id>" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"limit_bytes": <NEW_QUOTA_LIMIT>
}'25.16. deleteOrganizationQuotaSuperUser
Delete Organization Quota Super User.
25.16.1. DELETE /api/v1/superuser/users/{namespace}/quota/{quota_id}
Authorizations: oauth2_implicit (super:user)
25.16.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string | |
| path | quota_id required | string |
25.16.3. Responses
25.16.4. Example command
$ curl -X DELETE "https://quay-server.example.com/api/v1/superuser/users/<username>/quota/<quota_id>" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.17. createOrganizationQuotaSuperUser
Create Organization Quota Super User.
25.17.1. POST /api/v1/superuser/users/{namespace}/quota
Authorizations: oauth2_implicit (super:user)
25.17.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
25.17.3. Request body schema (application/json)
Description of a new organization quota
| Name | Description | Schema |
|---|---|---|
| limit_bytes optional | Number of bytes the organization is allowed | integer |
25.17.4. Responses
25.17.5. Example command
$ curl -X POST "https://quay-server.example.com/api/v1/superuser/users/<username>/quota" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"limit_bytes": <QUOTA_LIMIT>
}'25.18. listOrganizationQuotaSuperUser
List Organization Quota Super User.
25.18.1. GET /api/v1/superuser/users/{namespace}/quota
Authorizations: oauth2_implicit (super:user)
25.18.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
25.18.3. Responses
25.18.4. Example command
$ curl -X GET "https://quay-server.example.com/api/v1/superuser/users/<username>/quota" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.19. changeOrganization
Updates information about the specified organization.
25.19.1. PUT /api/v1/superuser/organizations/{name}
Authorizations: oauth2_implicit (super:user)
25.19.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | name required | The name of the organization being managed | string |
25.19.3. Request body schema (application/json)
Description of updates for an existing organization
| Name | Description | Schema |
|---|---|---|
| name optional | The new name for the organization | string |
25.19.4. Responses
25.19.5. Example command
$ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<new_organization_name>"
}' \
"https://<quay_server>/api/v1/superuser/organizations/<organization_name>"25.20. deleteOrganization
Deletes the specified organization.
25.20.1. DELETE /api/v1/superuser/organizations/{name}
Authorizations: oauth2_implicit (super:user)
25.20.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | name required | The name of the organizaton being managed | string |
25.20.3. Responses
25.20.4. Example command
$ curl -X DELETE \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/organizations/<organization_name>"25.21. approveServiceKey
Approve Service Key.
25.21.1. POST /api/v1/superuser/approvedkeys/{kid}
Authorizations: oauth2_implicit (super:user)
25.21.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | kid required | The unique identifier for a service key | string |
25.21.3. Request body schema (application/json)
Information for approving service keys
| Name | Description | Schema |
|---|---|---|
| notes optional | Optional approval notes | string |
25.21.4. Responses
25.21.5. Example command
$ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{
"notes": "<approval_notes>"
}' \
"https://<quay_server>/api/v1/superuser/approvedkeys/<kid>"25.22. deleteServiceKey
Delete Service Key.
25.22.1. DELETE /api/v1/superuser/keys/{kid}
Authorizations: oauth2_implicit (super:user)
25.22.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | kid required | The unique identifier for a service key | string |
25.22.3. Responses
25.22.4. Example command
$ curl -X DELETE \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/keys/<kid>"25.23. updateServiceKey
Update Service Key.
25.23.1. PUT /api/v1/superuser/keys/{kid}
Authorizations: oauth2_implicit (super:user)
25.23.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | kid required | The unique identifier for a service key | string |
25.23.3. Request body schema (application/json)
Description of updates for a service key
| Name | Description | Schema |
|---|---|---|
| name optional | The friendly name of a service key | string |
| metadata optional | The key/value pairs of this key’s metadata | object |
| expiration optional | The expiration date as a unix timestamp |
25.23.4. Responses
25.23.5. Example command
$ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<service_key_name>",
"metadata": {"<key>": "<value>"},
"expiration": <unix_timestamp>
}' \
"https://<quay_server>/api/v1/superuser/keys/<kid>"25.24. getServiceKey
Get Service Key.
25.24.1. GET /api/v1/superuser/keys/{kid}
Authorizations: oauth2_implicit (super:user)
25.24.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | kid required | The unique identifier for a service key | string |
25.24.3. Responses
25.24.4. Example command
$ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/keys/<kid>"25.25. getRepoBuildStatusSuperUser
Return the status for the builds specified by the build uuids.
25.25.1. GET /api/v1/superuser/{build_uuid}/status
Authorizations: oauth2_implicit (super:user)
25.25.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | build_uuid required | The UUID of the build | string |
25.25.3. Responses
25.25.4. Example command
$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/status" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.26. getRepoBuildSuperUser
Returns information about a build.
25.26.1. GET /api/v1/superuser/{build_uuid}/build
Authorizations: oauth2_implicit (super:user)
25.26.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | build_uuid required | The UUID of the build | string |
25.26.3. Responses
25.26.4. Example command
$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/build" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.27. getRepoBuildLogsSuperUser
Return the build logs for the build specified by the build uuid.
25.27.1. GET /api/v1/superuser/{build_uuid}/logs
Authorizations: oauth2_implicit (super:user)
25.27.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | build_uuid required | The UUID of the build | string |
25.27.3. Responses
25.27.4. Example command
$ curl -X GET "https://quay-server.example.com/api/v1/superuser/<build_uuid>/logs" \
-H "Authorization: Bearer <ACCESS_TOKEN>"25.28. getRegistrySize
Get Registry Size.
25.28.1. GET /api/v1/superuser/registrysize/
Authorizations: oauth2_implicit (super:user)
25.28.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
Description of a image registry size
| Name | Description | Schema |
|---|---|---|
| size_bytes* optional | Number of bytes the organization is allowed | integer |
| last_ran | integer | |
| queued | boolean | |
| running | boolean |
25.28.3. Responses
25.28.4. Example command
$ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
"https://<quay_server>/api/v1/superuser/registrysize/"25.29. postRegistrySize
Post Registry Size.
25.29.1. POST /api/v1/superuser/registrysize/
Authorizations: oauth2_implicit (super:user)
25.29.2. Path parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| path | namespace required | string |
25.29.3. Request body schema (application/json)
Description of a image registry size
| Name | Description | Schema |
|---|---|---|
| last_ran | integer | |
| queued | boolean | |
| running | boolean |
25.29.4. Responses
25.29.5. Example command
$ curl -X POST "https://quay-server.example.com/api/v1/superuser/registrysize/" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"namespace": "<namespace>",
"last_ran": 1700000000,
"queued": true,
"running": false
}'25.30. getSuperUserRepositoryMirrorHealth
Return a global repository mirror health summary for superusers.
25.30.1. GET /api/v1/superuser/mirror/health
Authorizations: oauth2_implicit (super:user)
Returns HTTP 200 when mirroring is healthy and HTTP 503 when unhealthy.
This endpoint requires a fresh login. A validated OAuth or SSO token satisfies the check. A password-based browser session must be within FRESH_LOGIN_TIMEOUT (default: 10m).
The response is a cluster-wide summary without repository-identifying issue samples. For namespace-scoped details, use GET /api/v1/repository/mirror/health?namespace=<orgname>&detailed=true. See getRepositoryMirrorHealth.
25.30.2. Responses
25.30.3. Example command
$ curl -X GET "https://<quay-server.example.com>/api/v1/superuser/mirror/health" \
-H "Authorization: Bearer <access_token>"
Substitute an OAuth access token that includes the super:user scope, or use a fresh superuser login session.
Example output
{
"healthy": true,
"workers": {
"active": 1,
"configured": 1,
"status": "healthy"
},
"repositories": {
"total": 0,
"syncing": 0,
"completed": 0,
"failed": 0,
"never_run": 0
},
"tags_pending": 0,
"last_check": "2026-07-16T20:11:17.064697Z",
"issues": []
}
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}