Skip to main content
Sign in with CostGraph lets an application you build authenticate people with their CostGraph account and read cost and usage data on their behalf. It uses standard OAuth 2.0 and OpenID Connect. Each client belongs to one tenant. Only users of that tenant can sign in through it, and its tokens can only read that tenant.

Create a client

Tenant admins create clients in Settings > OAuth clients.
  • A confidential client runs on a server and can keep a secret. CostGraph shows the client secret a single time, at creation. Rotate it to get a new one.
  • A public client, such as a single-page or desktop app, has no secret and sends only its client_id.
Every client must use PKCE, public or confidential.

Client ID Metadata Documents

Instead of registering, an application can host a JSON metadata document and use its URL as the client_id. CostGraph fetches the document when a user signs in. Your metadata document must be served over HTTPS. It must include:
  • client_id: The exact URL to this document
  • client_name: Your application’s name
  • redirect_uris: An array of redirect URLs
Optionally add:
  • token_endpoint_auth_method: Must be "none" or omitted
  • logo_uri: An HTTPS URL to a logo image
  • client_uri: An HTTPS URL to your website
  • tos_uri: An HTTPS URL to your terms of service
  • policy_uri: An HTTPS URL to your privacy policy
Example at https://app.example.com/oauth/client.json:
CostGraph verifies the domain hosting your metadata document and displays a verified badge on the consent screen and in Connected apps. The consent screen also links to your website, terms and privacy policy when you provide them. Non-HTTPS links are ignored. The badge names the domain that serves your metadata document. Desktop and command-line applications with only localhost redirect URIs see the consent screen on every sign-in, even after previous approvals. Applications that register dynamically, or that a tenant admin created in Settings > OAuth clients, keep working unchanged. The discovery document advertises client_id_metadata_document_supported: true, and authorization responses include an iss parameter.

Endpoints

Read every endpoint from the discovery document:
The same document is also served at /.well-known/oauth-authorization-server.

Sign in

CostGraph uses the authorization code flow with PKCE. The S256 method is required.
1

Send the user to CostGraph

Generate a random code_verifier, then derive code_challenge as the base64url SHA-256 of it. Redirect the user to the authorization endpoint:
The user reviews the permissions and approves. CostGraph redirects to your redirect_uri with code and state. The code expires after 1 minute.
2

Exchange the code for tokens

Confidential clients authenticate with client_secret_basic or client_secret_post. Public clients omit the secret and send client_id in the body.
The response contains access_token, refresh_token, expires_in, and, when you requested openid, id_token.
3

Call CostGraph

Send the access token as a bearer token. The user info endpoint requires the openid permission and returns 403 without it.

Permissions

Request permissions with the scope parameter. The user sees them on the approval screen. For how to call the Pricing API with these permissions, see Authentication.

Tokens

The following table lists the lifetime of each credential. Exchange a refresh token with grant_type=refresh_token. Each exchange returns a new refresh token, and you must store it. If you present a refresh token that was already exchanged (the previous one), CostGraph signs the user out of your app. Older tokens fail with invalid_grant. The id_token carries these claims:

Sign out

Revoke a token when the user signs out of your app. Confidential clients authenticate with the client secret:
Public clients send client_id instead:
Revoking any token from a sign-in ends that whole sign-in. Unknown tokens still return 200. Users can also remove your app themselves in Settings > Connected apps. If a tenant admin deletes the client, everyone is signed out of it.

Errors

Errors come from three places: the sign-in redirect, the token endpoints, and API calls.

Sign-in errors

The following errors are returned to your redirect_uri as the error query parameter.

Token errors

The token and revocation endpoints return these errors as JSON.

API errors

If you call an endpoint that your granted permissions don’t cover, CostGraph returns 403 with the message This application is not allowed to access this resource. Request the missing scope and have the user approve it again.

Next steps

MCP

Connect an AI agent to CostGraph.