canonical: https://jentic.com/apis/hubspot.com/hubspot-auth-oauth

# HubSpot Auth Oauth

The HubSpot OAuth API covers token introspection and refresh for HubSpot's OAuth 2.0 flow. GET /oauth/v1/access-tokens/{token} returns metadata for an access token including the user, the portal id, and the granted scopes, while GET /oauth/v1/refresh-tokens/{token} returns equivalent metadata for a refresh token. POST /oauth/v1/token completes the standard refresh-token grant to mint a new access token, and DELETE /oauth/v1/refresh-tokens/{token} revokes a refresh token. The endpoints are unauthenticated at the HTTP level because they take the token to inspect or exchange in the path or body.

## For AI agents

Inspect, refresh, and revoke HubSpot OAuth access and refresh tokens to manage the credential lifecycle for HubSpot integrations.

## Scope

Does not initiate the OAuth authorization code flow, render consent screens, or read CRM data - use only for inspecting, refreshing, and revoking HubSpot OAuth tokens.

## Capabilities

- Inspect a HubSpot OAuth access token to read user, portal, and scope metadata
- Inspect a refresh token to read its expiry and granted scopes
- Refresh a HubSpot access token using a refresh token grant
- Revoke a refresh token to terminate a HubSpot integration's session
- Verify the portal id encoded in a HubSpot OAuth credential before use

## Use cases

### Refresh an expired access token

HubSpot access tokens expire roughly every 30 minutes, so production integrations refresh them on demand. POST /oauth/v1/token with grant_type=refresh_token and the refresh token returns a new access token plus the refresh token's remaining lifetime. The integration stores the new access token and continues making calls.

Example prompt: Call POST /oauth/v1/token with grant_type=refresh_token, the client_id, client_secret, and refresh_token, then store the returned access_token

### Verify token scopes before a sensitive call

Before running a destructive workflow, an integration calls GET /oauth/v1/access-tokens/{token} to confirm the scopes attached to the credential. The response includes the user, hub_id, and scopes array, so the integration aborts if a required scope is missing rather than failing midway.

Example prompt: Call GET /oauth/v1/access-tokens/{token} and abort if the scopes array is missing the required crm.objects.contacts.write value

### Revoke a refresh token after uninstall

When a customer uninstalls a HubSpot app, the integration must revoke the stored refresh token so it cannot be used again. DELETE /oauth/v1/refresh-tokens/{token} invalidates the token, and a follow-up GET on the same path returns 404, confirming the revocation.

Example prompt: Call DELETE /oauth/v1/refresh-tokens/{token} with the stored refresh token, then GET the same path to confirm a 404 response

### Agent integration via Jentic

An auth-management agent can keep HubSpot credentials fresh on behalf of installed apps. Through Jentic the agent searches for the refresh operation, loads the schema, and executes the refresh-token grant. The client secret stays in your Jentic One instance and never enters the agent's context.

Example prompt: Search Jentic for 'refresh a hubspot oauth access token', load POST /oauth/v1/token, and execute with grant_type=refresh_token and the stored refresh token

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /oauth/v1/access-tokens/{token} | Retrieve OAuth access token metadata |
| GET | /oauth/v1/refresh-tokens/{token} | Retrieve refresh token metadata |
| DELETE | /oauth/v1/refresh-tokens/{token} | Revoke a refresh token |
| POST | /oauth/v1/token | Refresh an access token |

## Key resources

- **Access Tokens** — Read metadata for a HubSpot OAuth access token
- **Refresh Tokens** — Read or revoke a HubSpot OAuth refresh token
- **Tokens** — Refresh an access token using the refresh-token grant

## Why Jentic

- **Setup:** Wiring this HubSpot OAuth API by hand means driving the token exchange, inspecting access and refresh tokens, and handling revocation against api.hubapi.com yourself. Through Jentic you install once, import Auth Oauth from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** This API covers token exchange, inspection, and revocation, with the token carried in the URL path for the read operations, so limit the agent to the operations it needs, such as exchanging or inspecting a token. You choose that set, so revoking a refresh token with DELETE /oauth/v1/refresh-tokens/{token} is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth client secret and refresh token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'refresh a hubspot oauth access token', and Jentic returns POST /oauth/v1/token with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Account Info** — Use the access token from this API to read the connected portal's metadata
- **HubSpot Auth API** — Equivalent OAuth introspection and refresh endpoints under hubapi.com
- **Auth0 Authentication API** — Auth0 covers token introspection and refresh in a centralised identity platform
- **Okta API** — Okta provides token introspection and revocation for OAuth-protected applications

## FAQ

### What authentication does the HubSpot OAuth API use?

The four endpoints do not require a separate Authorization header - the token to be inspected or refreshed is supplied either in the path or in the request body. The refresh endpoint requires the OAuth client_id and client_secret in the body alongside the refresh_token. Through Jentic the client secret stays in the vault.

### Can I see which scopes a HubSpot access token has?

Yes. GET /oauth/v1/access-tokens/{token} returns a JSON body that includes the user, hub_id, and scopes array, so an integration can verify the granted permissions before calling endpoints that require specific scopes.

### What are the rate limits for the HubSpot OAuth API?

The spec does not declare per-endpoint limits. OAuth endpoints share HubSpot's broader rate limits, but the refresh endpoint should be called only when the access token is near expiry - refreshing on every call is wasteful and can trigger throttling at the account level.

### How do I refresh a HubSpot access token through Jentic?

Search Jentic for 'refresh a hubspot oauth access token', load the schema for POST /oauth/v1/token, and execute with grant_type=refresh_token, the client_id, client_secret, and refresh_token. Jentic returns the new access_token and its expires_in value.

### How do I revoke a refresh token after a customer uninstalls?

Call DELETE /oauth/v1/refresh-tokens/{token} with the refresh token. The endpoint returns 204 on success and the token is no longer usable. A follow-up GET on the same path returns 404, which confirms the revocation.

### Is the HubSpot OAuth API free?

All four endpoints are included with HubSpot's developer platform. There is no per-call charge for token introspection, refresh, or revocation.

### Can I limit what my agent is allowed to do with the HubSpot OAuth API?

Yes. Because Jentic One is self-hosted, your own rules decide which of the HubSpot OAuth operations the agent may call, so you can allow it to inspect a token with GET /oauth/v1/access-tokens/{token} or refresh one with POST /oauth/v1/token while withholding everything else. Destructive actions such as revoking a credential with DELETE /oauth/v1/refresh-tokens/{token} are not available to the agent unless you explicitly add that operation to its allowed set. Your OAuth client secret and refresh token are held only by your instance and injected at execution time, so the agent scopes what it can do without ever seeing the raw credentials.