How to Integrate a Third-Party App with Vultr OAuth

Vultr OAuth lets your application authenticate Vultr customers and call the Vultr API on their behalf, scoped to the permissions each customer consents to. A complete integration spans creating an OIDC provider, registering an application, authorizing it as a customer, and exchanging the resulting code for an access token your application uses against the API.

Follow this guide to integrate a third-party application with Vultr OAuth using the Vultr API, from provider creation through an authenticated API call. It uses the draft-mode allowlist so you can test the full flow before the application is approved for general use.

Create the Provider and Authorize the Application

1. Send a POST request to the Create OIDC Provider endpoint to create a provider. Replace PROVIDER-NAME with a name.

   console Copy

   $ curl "https://api.vultr.com/v2/oidc/provider" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "provider": {
               "name": "PROVIDER-NAME"
           }
       }'
   

   Explain Code

   Note the id to use as the oidc_provider_id in the next step.

2. Send a POST request to the Create OAuth Client endpoint to register the application. Replace APP-NAME with a name, CALLBACK-URL with your callback URL, and PROVIDER-ID with the provider id.

   console Copy

   $ curl "https://api.vultr.com/v2/oauth/clients" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "name": "APP-NAME",
           "callback_urls": ["CALLBACK-URL"],
           "oidc_provider_id": "PROVIDER-ID"
       }'
   

   Explain Code

   Note the id and record the secret, which is shown only once.

3. Send a POST request to the Attach OAuth Scope endpoint to define the application's permissions. Replace {client-id} with the application id and SOURCE-POLICY-ID with an IAM policy id from your organization.

   console Copy

   $ curl "https://api.vultr.com/v2/oauth/clients/{client-id}/scopes" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "policy_id": "SOURCE-POLICY-ID"
       }'
   

   Explain Code

   A successful request returns an HTTP 200 OK response. The application owner's account is added to the draft-mode allowlist automatically, so it can authorize the application before approval.

4. Send a POST request to the Authorize OAuth Application endpoint to grant access as the customer. Replace CLIENT-ID with the application id and CALLBACK-URL with the registered callback URL.

   console Copy

   $ curl "https://api.vultr.com/v2/oauth/authorize" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "client_id": "CLIENT-ID",
           "redirect_uri": "CALLBACK-URL",
           "response_type": "code",
           "approve": true
       }'
   

   Explain Code

   A successful request returns an HTTP 200 OK response with a one-time code and the oidc_provider_id. Note both values for the token exchange. The authorization code is single-use and expires 10 minutes after it is issued.

Exchange the Code and Call the API

1. Send a POST request to the Token endpoint to exchange the code. Replace {provider-id} with the provider id, CLIENT-ID and CLIENT-SECRET with the application credentials, AUTH-CODE with the code, and CALLBACK-URL with the callback URL.

   console Copy

   $ curl "https://api.vultr.com/v2/oidc/provider/{provider-id}/token" \
       -X POST \
       -H "Authorization: Basic $(printf '%s:%s' "CLIENT-ID" "CLIENT-SECRET" | base64)" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       --data-urlencode "grant_type=authorization_code" \
       --data-urlencode "code=AUTH-CODE" \
       --data-urlencode "redirect_url=CALLBACK-URL"
   

   Explain Code

   The response contains an access_token and a refresh_token. Note the access_token for the next step.

   Note

   • Refresh tokens rotate on every use. Store the refresh_token returned by each response, because the previous one stops working immediately.
   • Reusing an already-rotated refresh token revokes the entire token family and forces the customer to re-consent.
   • Each refresh token has a 30-day sliding expiry that resets on every successful refresh.

2. Send a request to a Vultr API endpoint with the access token as a Bearer token. Replace ACCESS-TOKEN with the access_token.

   console Copy

   $ curl "https://api.vultr.com/v2/account" \
       -X GET \
       -H "Authorization: Bearer ACCESS-TOKEN"
   

   Explain Code

   The response contains the account data, scoped to the permissions the customer consented to. The integration is now complete: your application holds a token it can use against the Vultr API, and it can refresh that token without sending the customer through consent again.