Chapter 17. Using the Red Hat Quay API Red Hat Quay provides a full OAuth 2 , RESTful API. [OAuth 2] RESTful API provides the following benefits: It is available from endpoint /api/v1 endpoint of your Red Hat Quay host. For example, https://<quay-server.example.com>/api/v1 . It allows users to connect to endpoints through their browser to GET , POST , DELETE , and PUT Red Hat Quay settings by enabling the Swagger UI. It can be accessed by applications that make API calls and use OAuth tokens. It sends and receives data as JSON. The following section describes how to access the Red Hat Quay API so that it can be used with your deployment. 17.1. Accessing the Quay API from Quay.io If you don't have your own Red Hat Quay cluster running yet, you can explore the Red Hat Quay API available from Quay.io from your web browser: The API Explorer that appears shows Quay.io API endpoints. You will not see superuser API endpoints or endpoints for Red Hat Quay features that are not enabled on Quay.io (such as Repository Mirroring). From API Explorer, you can get, and sometimes change, information on: Billing, subscriptions, and plans Repository builds and build triggers Error messages and global messages Repository images, manifests, permissions, notifications, vulnerabilities, and image signing Usage logs Organizations, members and OAuth applications User and robot accounts and more... Select to open an endpoint to view the Model Schema for each part of the endpoint. Open an endpoint, enter any required parameters (such as a repository name or image), then select the Try it out! button to query or change settings associated with a Quay.io endpoint. 17.2. Creating a v1 OAuth access token OAuth access tokens are credentials that allow you to access protected resources in a secure manner. With Red Hat Quay, you must create an OAuth access token before you can access the API endpoints of your organization. Use the following procedure to create an OAuth access token. Prerequisites You have logged in to Red Hat Quay as an administrator. Procedure On the main page, select an Organization. In the navigation pane, select Applications . Click Create New Application and provide a new application name, then press Enter . On the OAuth Applications page, select the name of your application. Optional. Enter the following information: Application Name Homepage URL Description Avatar E-mail Redirect/Callback URL prefix In the navigation pane, select Generate Token . Check the boxes for the following options: Administer Organization Administer Repositories Create Repositories View all visible repositories Read/Write to any accessible repositories Super User Access Administer User Read User Information Click Generate Access Token . You are redirected to a new page. Review the permissions that you are allowing, then click Authorize Application . Confirm your decision by clicking Authorize Application . You are redirected to the Access Token page. Copy and save the access token. Important This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page. 17.3. Creating an OCI referrers OAuth access token In some cases, you might want to create an OCI referrers OAuth access token. This token is used to list OCI referrers of a manifest under a repository. Procedure Update your config.yaml file to include the FEATURE_REFERRERS_API: true field. For example: # ... FEATURE_REFERRERS_API: true # ... Enter the following command to Base64 encode your credentials: USD echo -n '<username>:<password>' | base64 Example output abcdeWFkbWluOjE5ODlraWROZXQxIQ== Enter the following command to use the base64 encoded string and modify the URL endpoint to your Red Hat Quay server: USD curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq Example output { "token": "<example_secret> } 17.4. Reassigning an OAuth access token Organization administrators can assign OAuth API tokens to be created by other user's with specific permissions. This allows the audit logs to be reflected accurately when the token is used by a user that has no organization administrative permissions to create an OAuth API token. Note The following procedure only works on the current Red Hat Quay UI. It is not currently implemented in the Red Hat Quay v2 UI. Prerequisites You are logged in as a user with organization administrative privileges, which allows you to assign an OAuth API token. Note OAuth API tokens are used for authentication and not authorization. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints. For more information, see Managing access to repositories . Procedure Optional. If not already, update your Red Hat Quay config.yaml file to include the FEATURE_ASSIGN_OAUTH_TOKEN: true field: # ... FEATURE_ASSIGN_OAUTH_TOKEN: true # ... Optional. Restart your Red Hat Quay registry. Log in to your Red Hat Quay registry as an organization administrator. Click the name of the organization in which you created the OAuth token for. In the navigation pane, click Applications . Click the proper application name. In the navigation pane, click Generate Token . Click Assign another user and enter the name of the user that will take over the OAuth token. Check the boxes for the desired permissions that you want the new user to have. For example, if you only want the new user to be able to create repositories, click Create Repositories . Important Permission control is defined by the team role within an organization and must be configured regardless of the options selected here. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints. Solely checking the Super User Access box does not actually grant the user this permission. Superusers must be configured via the config.yaml file and the box must be checked here. Click Assign token . A popup box appears that confirms authorization with the following message and shows you the approved permissions: This will prompt user <username> to generate a token with the following permissions: repo:create Click Assign token in the popup box. You are redirected to a new page that displays the following message: Token assigned successfully Verification After reassigning an OAuth token, the assigned user must accept the token to receive the bearer token, which is required to use API endpoints. Request that the assigned user logs into the Red Hat Quay registry. After they have logged in, they must click their username under Users and Organizations . In the navigation pane, they must click External Logins And Applications . Under Authorized Applications , they must confirm the application by clicking Authorize Application . They are directed to a new page where they must reconfirm by clicking Authorize Application . They are redirected to a new page that reveals their bearer token. They must save this bearer token, as it cannot be viewed again. 17.5. Accessing your Quay API from a web browser By enabling Swagger, you can access the API for your own Red Hat Quay instance through a web browser. This URL exposes the Red Hat Quay API explorer via the Swagger UI and this URL: That way of accessing the API does not include superuser endpoints that are available on Red Hat Quay installations. Here is an example of accessing a Red Hat Quay API interface running on the local system by running the swagger-ui container image: With the swagger-ui container running, open your web browser to localhost port 8888 to view API endpoints via the swagger-ui container. To avoid errors in the log such as "API calls must be invoked with an X-Requested-With header if called from a browser," add the following line to the config.yaml on all nodes in the cluster and restart Red Hat Quay: 17.6. Accessing the Red Hat Quay API from the command line You can use the curl command to GET, PUT, POST, or DELETE settings via the API for your Red Hat Quay cluster. Replace <token> with the OAuth access token you created earlier to get or change settings in the following examples.

Commands:
https://docs.quay.io/api/swagger/
FEATURE_REFERRERS_API: true
echo -n '<username>:<password>' | base64
abcdeWFkbWluOjE5ODlraWROZXQxIQ==
curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq
{ "token": "<example_secret> }
FEATURE_ASSIGN_OAUTH_TOKEN: true
This will prompt user <username> to generate a token with the following permissions: repo:create
Token assigned successfully
https://<yourquayhost>/api/v1/discovery.
export SERVER_HOSTNAME=<yourhostname> sudo podman run -p 8888:8080 -e API_URL=https://USDSERVER_HOSTNAME:8443/api/v1/discovery docker.io/swaggerapi/swagger-ui
BROWSER_API_CALLS_XHR_ONLY: false