Authentication - drio Docs

Authenticate against the drio management API with OAuth 2.0, PKCE, and bearer tokens.

This page is for developers using the drio management API. Public routes such as template listing do not require a token, but protected routes do.

The Auth Model In One View

Start with drio's discovery documents, then use the AuthKit issuer they advertise.

drio owns:

the protected resource you want to call
the discovery entrypoints on the API host
bearer-token validation on protected routes

AuthKit owns:

dynamic client registration
authorization
token exchange
refresh token exchange

That means your client should treat drio as the API resource server and AuthKit as the OAuth authorization server.

When You Need Auth

These routes require a bearer token:

/api/v1/me
/api/v1/apps
/api/v1/apps/{appId}
/api/v1/apps/{appId}/config
/api/v1/apps/{appId}/commands

Start With Discovery

Most OAuth-aware clients should begin with:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

These discovery documents tell the client:

which AuthKit issuer to use
where to authorize
where to exchange tokens
where to register clients
which scopes are supported

Supported Flow

The current model supports:

dynamic client registration
authorization code flow
PKCE
refresh tokens
bearer tokens on protected routes

Typical OAuth Flow

1. Discover the auth server

GET /.well-known/oauth-authorization-server

Save the returned authorization_endpoint, token_endpoint, and registration_endpoint. Those endpoints live on drio's AuthKit issuer.

2. Register your client and redirect URIs

curl -X POST https://AUTHKIT_ISSUER/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

Save the returned client_id. You will use it during both authorization and token exchange.

3. Redirect the user to authorize

GET https://AUTHKIT_ISSUER/oauth2/authorize?client_id=...&response_type=code&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=...

AuthKit handles sign-in and redirects back to your app with the authorization code for that registered client.

4. Exchange the code for tokens

curl -X POST https://AUTHKIT_ISSUER/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=CLIENT_ID&code=AUTH_CODE&code_verifier=CODE_VERIFIER&redirect_uri=https://example.com/callback&grant_type=authorization_code"

5. Call protected routes

curl https://getdrio.com/api/v1/apps \
  -H "Authorization: Bearer ACCESS_TOKEN"

6. Refresh when needed

curl -X POST https://AUTHKIT_ISSUER/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=CLIENT_ID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN"

What Stays Stable

For the authorization code flow to work cleanly:

keep the same registered redirect_uri during authorize and token exchange
keep the client_id returned by dynamic client registration
send PKCE fields during authorize and token exchange
use the resulting bearer token only on protected drio routes

drio no longer brokers the OAuth code flow. Your client talks directly to AuthKit once discovery is complete.

Scopes

Current supported scopes:

openid
profile
email

Response Shapes

AuthKit's registration and token endpoints return OAuth-style responses. Protected drio resource routes use the drio API error envelope instead. See Errors.

Success:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Failure:

{
  "error": "invalid_request",
  "error_description": "Missing required field: refresh_token"
}