{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Auth Oauth",
    "version" : "v1",
    "x-hubspot-product-tier-requirements" : {
      "marketing" : "FREE",
      "sales" : "FREE",
      "service" : "FREE",
      "cms" : "FREE",
      "commerce" : "FREE",
      "crmHub" : "FREE",
      "dataHub" : "FREE"
    }
  },
  "servers" : [ {
    "url" : "https://api.hubapi.com"
  } ],
  "tags" : [ {
    "name" : "Access_Tokens"
  }, {
    "name" : "Refresh_Tokens"
  }, {
    "name" : "Tokens"
  } ],
  "paths" : {
    "/oauth/v1/access-tokens/{token}" : {
      "get" : {
        "tags" : [ "Access_Tokens" ],
        "summary" : "Retrieve OAuth token metadata",
        "description" : "Retrieve a token's metadata, including the email address of the user that the token was created for and the ID of the account it's associated with.\n\nNote: HubSpot access tokens will fluctuate in size as the information that's encoded in them changes over time. It's recommended to allow for tokens to be up to 300 characters to account for any potential changes.",
        "operationId" : "get-/oauth/v1/access-tokens/{token}_get",
        "parameters" : [ {
          "name" : "token",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/AccessTokenInfoResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "deprecated" : true
      }
    },
    "/oauth/v1/refresh-tokens/{token}" : {
      "get" : {
        "tags" : [ "Refresh_Tokens" ],
        "summary" : "Retrieve refresh token metadata",
        "description" : "Retrieve a refresh token's metadata, including the email address of the user that the token was created for and the ID of the account it's associated with. Learn more about [refresh tokens](https://developers.hubspot.com/docs/guides/api/app-management/oauth-tokens#generate-initial-access-and-refresh-tokens).",
        "operationId" : "get-/oauth/v1/refresh-tokens/{token}_get",
        "parameters" : [ {
          "name" : "token",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RefreshTokenInfoResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "deprecated" : true
      },
      "delete" : {
        "tags" : [ "Refresh_Tokens" ],
        "summary" : "Delete a refresh token",
        "description" : "Delete a refresh token, typically after a user uninstalls your app. Access tokens generated with the refresh token will not be affected.\n\nThis will not uninstall the application from HubSpot or inhibit data syncing between an account and the app.",
        "operationId" : "delete-/oauth/v1/refresh-tokens/{token}_archive",
        "parameters" : [ {
          "name" : "token",
          "in" : "path",
          "description" : "",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No content",
            "content" : { }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "deprecated" : true
      }
    },
    "/oauth/v1/token" : {
      "post" : {
        "tags" : [ "Tokens" ],
        "summary" : "Refresh an access token",
        "description" : "Use a [previously obtained refresh token](#get-oauth-2.0-access-and-refresh-tokens) to generate a new access token. \n\nAccess tokens are short lived. You can check the `expires_in` parameter when generating an access token to determine its lifetime (in seconds). If you need offline access to HubSpot data, store the refresh token you get when [initiating your OAuth integration](https://developers.hubspot.com/docs/guides/api/app-management/oauth-tokens#initiating-oauth-access) and use it to generate a new access token once the initial one expires.\n\nNote: HubSpot access tokens will fluctuate in size as the information that's encoded in them changes over time. It's recommended to allow for tokens to be up to 300 characters to account for any potential changes.",
        "operationId" : "post-/oauth/v1/token_create",
        "parameters" : [ {
          "name" : "client_secret",
          "in" : "query",
          "description" : "",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "refresh_token",
          "in" : "query",
          "description" : "",
          "required" : false,
          "style" : "form",
          "explode" : true,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/x-www-form-urlencoded" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "client_id" : {
                    "type" : "string",
                    "example" : null
                  },
                  "client_secret" : {
                    "type" : "string",
                    "example" : null
                  },
                  "code" : {
                    "type" : "string",
                    "example" : null
                  },
                  "code_verifier" : {
                    "type" : "string",
                    "example" : null
                  },
                  "grant_type" : {
                    "type" : "string",
                    "example" : null,
                    "enum" : [ "authorization_code", "client_credentials", "refresh_token" ]
                  },
                  "redirect_uri" : {
                    "type" : "string",
                    "example" : null
                  },
                  "refresh_token" : {
                    "type" : "string",
                    "example" : null
                  },
                  "scope" : {
                    "type" : "string",
                    "example" : null
                  }
                },
                "example" : null
              },
              "example" : null
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/TokenResponseIF"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "AccessTokenInfoResponse" : {
        "required" : [ "app_id", "expires_in", "hub_id", "scopes", "token", "token_type", "user_id" ],
        "type" : "object",
        "properties" : {
          "app_id" : {
            "type" : "integer",
            "description" : "The ID of the application associated with the access token.",
            "format" : "int32",
            "example" : null
          },
          "expires_in" : {
            "type" : "integer",
            "description" : "The time in seconds until the access token expires.",
            "format" : "int64",
            "example" : null
          },
          "hub_domain" : {
            "type" : "string",
            "description" : "The domain of the HubSpot account associated with the access token.",
            "example" : null
          },
          "hub_id" : {
            "type" : "integer",
            "description" : "The ID of the HubSpot account associated with the access token.",
            "format" : "int32",
            "example" : null
          },
          "is_private_distribution" : {
            "type" : "boolean",
            "description" : "Indicates whether the token is for a privately distributed application. If false, it is marketplace distributed.",
            "example" : null
          },
          "scopes" : {
            "type" : "array",
            "description" : "An array of strings indicating the scopes",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "signed_access_token" : {
            "$ref" : "#/components/schemas/SignedAccessToken"
          },
          "token" : {
            "type" : "string",
            "description" : "The access token string used to make API calls.",
            "example" : null
          },
          "token_type" : {
            "type" : "string",
            "description" : "The type of token, typically indicating the authentication scheme. Typically `bearer`.",
            "example" : null
          },
          "user" : {
            "type" : "string",
            "description" : "The email address of the hubspot user for whom the access token was created.",
            "example" : null
          },
          "user_id" : {
            "type" : "integer",
            "description" : "The ID of the hubspot user for whom the access token was created.",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null
      },
      "AccessTokenResponse" : {
        "type" : "object",
        "properties" : {
          "access_token" : {
            "type" : "string",
            "example" : null
          },
          "expires_in" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          },
          "hub_id" : {
            "type" : "integer",
            "format" : "int32",
            "example" : null
          },
          "id_token" : {
            "type" : "string",
            "example" : null
          },
          "refresh_token" : {
            "type" : "string",
            "example" : null
          },
          "scopes" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "token_type" : {
            "type" : "string",
            "example" : null
          },
          "token_use" : {
            "type" : "string",
            "example" : null,
            "default" : "access_token",
            "enum" : [ "access_token" ]
          },
          "user_id" : {
            "type" : "integer",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null,
        "x-hubspot-sub-type-impl" : true
      },
      "ClientCredentialsTokenResponse" : {
        "type" : "object",
        "properties" : {
          "access_token" : {
            "type" : "string",
            "example" : null
          },
          "expires_in" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          },
          "hub_id" : {
            "type" : "integer",
            "format" : "int32",
            "example" : null
          },
          "id_token" : {
            "type" : "string",
            "example" : null
          },
          "scopes" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "token_type" : {
            "type" : "string",
            "example" : null
          },
          "token_use" : {
            "type" : "string",
            "example" : null,
            "default" : "client_credentials",
            "enum" : [ "client_credentials" ]
          },
          "user_id" : {
            "type" : "integer",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null,
        "x-hubspot-sub-type-impl" : true
      },
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}"
          },
          "correlationId" : {
            "type" : "string",
            "description" : "A unique identifier for the request. Include this value with any error reports or support tickets",
            "format" : "uuid",
            "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf"
          },
          "errors" : {
            "type" : "array",
            "description" : "further information about the error",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "example" : {
          "message" : "Invalid input (details will vary based on the error)",
          "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf",
          "category" : "VALIDATION_ERROR",
          "links" : {
            "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base"
          }
        }
      },
      "ErrorDetail" : {
        "required" : [ "message" ],
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "The status code associated with the error detail",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{missingScopes=[scope1, scope2]}"
          },
          "in" : {
            "type" : "string",
            "description" : "The name of the field or parameter in which the error was found.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "example" : null
      },
      "RefreshTokenInfoResponse" : {
        "required" : [ "client_id", "hub_id", "scopes", "token", "token_type", "user_id" ],
        "type" : "object",
        "properties" : {
          "client_id" : {
            "type" : "string",
            "description" : "The client ID of the application that the refresh token was issued for.",
            "example" : null
          },
          "hub_domain" : {
            "type" : "string",
            "description" : "The domain of the HubSpot account associated with the refresh token.",
            "example" : null
          },
          "hub_id" : {
            "type" : "integer",
            "description" : "The ID of the HubSpot account associated with the refresh token.",
            "format" : "int32",
            "example" : null
          },
          "scopes" : {
            "type" : "array",
            "description" : "An array of strings detailing the scopes",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "token" : {
            "type" : "string",
            "description" : "The access token string used to make API calls.",
            "example" : null
          },
          "token_type" : {
            "type" : "string",
            "description" : "The type of token, typically indicating the OAuth token type. Typically `bearer`.",
            "example" : null
          },
          "user" : {
            "type" : "string",
            "description" : "The email address of the hubspot user associated with the refresh token.",
            "example" : null
          },
          "user_id" : {
            "type" : "integer",
            "description" : "The ID of the hubspot user associated with the refresh token.",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null
      },
      "SignedAccessToken" : {
        "required" : [ "appId", "expiresAt", "hubId", "hublet", "installingUserId", "isPrivateDistribution", "isServiceAccount", "isUserLevel", "newSignature", "scopeToScopeGroupPks", "scopes", "signature", "trialScopeToScopeGroupPks", "trialScopes", "userId" ],
        "type" : "object",
        "properties" : {
          "appId" : {
            "type" : "integer",
            "description" : "The ID of the application associated with the access token.",
            "format" : "int32",
            "example" : null
          },
          "expiresAt" : {
            "type" : "integer",
            "description" : "The timestamp indicating when the access token will expire.",
            "format" : "int64",
            "example" : null
          },
          "hubId" : {
            "type" : "integer",
            "description" : "The ID of the HubSpot account associated with the access token.",
            "format" : "int32",
            "example" : null
          },
          "hublet" : {
            "type" : "string",
            "description" : "The specific regional data center where the account is hosted.",
            "example" : null
          },
          "installingUserId" : {
            "type" : "integer",
            "description" : "The ID of the user who installed the application.",
            "format" : "int32",
            "example" : null
          },
          "isPrivateDistribution" : {
            "type" : "boolean",
            "description" : "Indicates whether the token is for a privately distributed application. If false, it is marketplace distributed.",
            "example" : null
          },
          "isServiceAccount" : {
            "type" : "boolean",
            "description" : "Indicates whether the access token is associated with a service account. Meaning it is decoupled from the user who installed it.",
            "example" : null
          },
          "isUserLevel" : {
            "type" : "boolean",
            "description" : "Indicates whether the access token is issued at the user level. Meaning the app is configured to allow multiple installs of the same app on a hub.",
            "example" : null
          },
          "newSignature" : {
            "type" : "string",
            "description" : "The updated cryptographic signature for the access token.",
            "example" : null
          },
          "scopeToScopeGroupPks" : {
            "type" : "string",
            "description" : "A mapping of scopes to their corresponding scope group primary keys.",
            "example" : null
          },
          "scopes" : {
            "type" : "string",
            "description" : "The permissions granted to the access token.",
            "example" : null
          },
          "signature" : {
            "type" : "string",
            "description" : "The cryptographic signature used to verify the integrity of the access token.",
            "example" : null
          },
          "trialScopeToScopeGroupPks" : {
            "type" : "string",
            "description" : "A mapping of trial scopes to their corresponding scope group primary keys.",
            "example" : null
          },
          "trialScopes" : {
            "type" : "string",
            "description" : "The trial scopes included in the access token.",
            "example" : null
          },
          "userId" : {
            "type" : "integer",
            "description" : "The ID of the hubspot user associated with the access token.",
            "format" : "int32",
            "example" : null
          }
        },
        "example" : null
      },
      "TokenResponseIF" : {
        "properties" : { },
        "example" : null,
        "oneOf" : [ {
          "$ref" : "#/components/schemas/AccessTokenResponse"
        }, {
          "$ref" : "#/components/schemas/ClientCredentialsTokenResponse"
        } ]
      }
    },
    "responses" : {
      "Error" : {
        "description" : "An error occurred.",
        "content" : {
          "*/*" : {
            "schema" : {
              "$ref" : "#/components/schemas/Error"
            },
            "example" : null
          }
        }
      }
    },
    "securitySchemes" : {
      "developer_hapikey" : {
        "type" : "apiKey",
        "name" : "hapikey",
        "in" : "query"
      },
      "oauth2" : {
        "type" : "oauth2",
        "flows" : {
          "authorizationCode" : {
            "authorizationUrl" : "https://app.hubspot.com/oauth/authorize",
            "tokenUrl" : "https://api.hubapi.com/oauth/v1/token",
            "scopes" : { }
          }
        }
      },
      "private_apps" : {
        "type" : "apiKey",
        "name" : "private-app",
        "in" : "header"
      },
      "private_apps_legacy" : {
        "type" : "apiKey",
        "name" : "private-app-legacy",
        "in" : "header"
      }
    }
  },
  "x-hubspot-available-client-libraries" : [ "Node", "Python", "Ruby", "PHP" ],
  "x-hubspot-product-tier-requirements" : {
    "marketing" : "FREE",
    "sales" : "FREE",
    "service" : "FREE",
    "cms" : "FREE",
    "commerce" : "FREE",
    "crmHub" : "FREE",
    "dataHub" : "FREE"
  }
}