Charthop oauth API
The oauth API from Charthop — 17 operation(s) for oauth.
OpenAPI Specification
swagger: '2.0'
info:
description: REST API for ChartHop
version: V1.0.0
title: ChartHop access oauth API
contact:
name: ChartHop
url: https://www.charthop.com
email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: oauth
paths:
/oauth/app/{appName}:
get:
tags:
- oauth
summary: Process an Oauth2 redirect request from an access request for an app installation, storing the accessToken and refreshToken as secrets for the app
operationId: handleRedirect
produces:
- application/json
parameters:
- name: token
in: cookie
required: false
type: string
- name: appName
in: path
description: App name
required: true
type: string
- name: state
in: query
description: State, containing orgId and appUserId
required: false
type: string
- name: code
in: query
description: Temporary authorization code
required: true
type: string
responses:
'400':
description: bad request
'404':
description: not found
/oauth/credentials:
post:
tags:
- oauth
summary: Return a ChartHop authorization token, given a username and password
operationId: issueAccessTokenFromCredentials
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
parameters:
- name: username
in: formData
description: Username to authenticate
required: false
type: string
- name: password
in: formData
description: Password to authenticate
required: false
type: string
- name: scope
in: formData
description: Requested access scope or scopes (space separated)
required: false
type: string
- name: client_id
in: formData
description: client id
required: false
type: string
- name: code_challenge
in: formData
description: code_challenge
required: false
type: string
- name: code_challenge_method
in: formData
description: code_challenge_method
required: false
type: string
- name: redirect_uri
in: formData
description: redirect_uri
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
'400':
description: invalid credentials
/oauth/join:
post:
tags:
- oauth
summary: Return a JOIN token to be used for new user operations
operationId: join
produces:
- application/json
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
/oauth/loginWithToken:
post:
tags:
- oauth
summary: Return a ChartHop authorization token, given a login token
operationId: issueAccessTokenFromLoginToken
produces:
- application/json
parameters:
- name: scope
in: query
description: Requested access scope or scopes (space separated)
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
'400':
description: invalid credentials
/oauth/mcp/approve:
post:
tags:
- oauth
summary: Approve an MCP authorization grant and issue an authorization code
operationId: approveMcpGrant
consumes:
- application/json
produces:
- application/json
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/McpApproveRequest'
responses:
'200':
description: successful operation
'400':
description: bad request
'403':
description: forbidden
'404':
description: not found
/oauth/mcp/grant-info:
get:
tags:
- oauth
summary: Describe a pending MCP authorization grant
operationId: getMcpGrantInfo
produces:
- application/json
parameters:
- name: clientId
in: query
description: The client's CIMD URL
required: true
type: string
- name: resource
in: query
description: The MCP server URL being authorized
required: true
type: string
- name: redirectUri
in: query
description: The client's OAuth redirect URI
required: true
type: string
responses:
'200':
description: successful operation
'400':
description: bad request
'403':
description: forbidden
'404':
description: not found
/oauth/org/{orgIdentifier}/app/{appName}/{appUserId}:
get:
tags:
- oauth
summary: Retrieve the oauth uri the user should be directed to in order to start the oauth flow
operationId: getOauthConnectUri
produces:
- application/json
parameters:
- name: orgIdentifier
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: appName
in: path
description: App name
required: true
type: string
- name: appUserId
in: path
description: App user id
required: true
type: string
- name: returnTo
in: query
description: Where to return the user
required: true
type: string
enum:
- INSTALL
- MANAGE
- SELF_SERVE
- AGENT
- AI_CHAT
- name: finchAppType
in: query
description: The type of Finch app being installed
required: false
type: string
enum:
- ALL
- AUTOMATED
- SANDBOX_FINCH
- SANDBOX_PROVIDER
- name: tokenLevel
in: query
description: For OAUTH apps, whether to create a shared org or per-user connection
required: false
type: string
enum:
- ORG
- USER
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/ConnectUriResponse'
'400':
description: bad request
'403':
description: forbidden
'404':
description: not found
/oauth/org/{orgIdentifier}/app/{appUserId}/oauth/connection:
get:
tags:
- oauth
summary: Whether the app installation has an active org-level OAuth connection
operationId: getAppOauthConnection
produces:
- application/json
parameters:
- name: orgIdentifier
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: appUserId
in: path
description: App user id
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AppOauthConnectionStatus'
'403':
description: forbidden
'404':
description: not found
/oauth/org/{orgIdentifier}/app/{appUserId}/oauth/user:
get:
tags:
- oauth
summary: List the per-user OAuth connections for an app installation
operationId: listAppOauthUserConnections
produces:
- application/json
parameters:
- name: orgIdentifier
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: appUserId
in: path
description: App user id
required: true
type: string
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/AppOauthUserConnection'
'403':
description: forbidden
'404':
description: not found
delete:
tags:
- oauth
summary: Revoke one or more per-user OAuth connections for an app installation
operationId: revokeAppOauthTokens
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgIdentifier
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: appUserId
in: path
description: App user id
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/RevokeAppOauthTokensRequest'
responses:
'403':
description: forbidden
'404':
description: not found
/oauth/revoke:
post:
tags:
- oauth
summary: Delete the current Oauth2 bearer token (for signout)
operationId: revokeToken
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
parameters:
- name: token
in: formData
description: Token to revoke
required: true
type: string
responses:
'200':
description: token revoked
/oauth/sendLoginToken:
post:
tags:
- oauth
summary: Send a login ("magic link") email
operationId: sendLoginToken
produces:
- application/json
parameters:
- name: body
in: body
description: User email address
required: true
schema:
$ref: '#/definitions/EmailRequest'
responses:
'204':
description: email sent
/oauth/sso/{idp}/access-token:
get:
tags:
- oauth
summary: Exchange a one-time use Auth Code for the IDP access token response
operationId: getIdpAccessTokenResponse
produces:
- application/json
parameters:
- name: idp
in: path
description: Identity provider of SSO login (e.g. adp)
required: true
type: string
- name: authCode
in: query
description: A one-time use Auth Code
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/IdpAccessTokenResponse'
'400':
description: bad request
'404':
description: not found
/oauth/sso/{idp}/login:
get:
tags:
- oauth
summary: Login via the auth endpoint
operationId: ssoAuthLogin
produces:
- application/json
parameters:
- name: idp
in: path
description: Identity provider of SSO login (e.g. adp)
required: true
type: string
responses:
'400':
description: bad request
'404':
description: not found
/oauth/token:
post:
tags:
- oauth
summary: Return an Oauth2 Authorization bearer token
operationId: issueAccessToken
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
parameters:
- name: grant_type
in: formData
description: Type of grant; 'password', 'refresh_token', 'authorization_code' supported
required: false
type: string
- name: code
in: formData
description: Authorization code
required: false
type: string
- name: redirect_uri
in: formData
description: Redirect URI
required: false
type: string
format: uri
- name: client_id
in: formData
description: Client id
required: false
type: string
- name: refresh_token
in: formData
description: Refresh token
required: false
type: string
- name: code_verifier
in: formData
description: Code verifier
required: false
type: string
- name: resource
in: formData
description: Target resource (RFC 8707)
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
'400':
description: invalid credentials
delete:
tags:
- oauth
summary: Delete the current Oauth2 bearer token (for signout)
operationId: deleteToken
produces:
- application/json
responses:
'204':
description: token deleted
'401':
description: not authorized
/oauth/token/attenuate:
post:
tags:
- oauth
summary: Given an existing token, issue a new token with a reduced set of scopes
operationId: attenuateToken
produces:
- application/json
parameters:
- name: scope
in: query
description: Requested access scope or scopes (space separated)
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
/oauth/token/sso/{type}:
post:
tags:
- oauth
summary: Return an Oauth2 Authorization bearer token, given a SSO id token
operationId: issueSsoToken
produces:
- application/json
parameters:
- name: type
in: path
description: type of SSO request (google or microsoft)
required: true
type: string
- name: createOrg
in: query
description: automatically create org if possible to do so
required: false
type: boolean
- name: signupSource
in: query
description: sign up source (self-serve, connect, or sequoia)
required: false
type: string
enum:
- ADP_MARKETPLACE
- SELF_SERVE
- SELF_SERVE_TEST
- SEQUOIA_ONE
- CONNECT
- name: utmParams
in: query
description: utm params (used in salesforce for lead tracking)
required: false
type: string
- name: email
in: query
description: sign up email address
required: false
type: string
- name: body
in: body
description: access token request
required: true
schema:
$ref: '#/definitions/AccessTokenRequest'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
'400':
description: invalid credentials
/oauth/token/view:
post:
tags:
- oauth
summary: Return a view-as token
operationId: issueViewToken
produces:
- application/json
parameters:
- name: body
in: body
description: request on whom to view as
required: true
schema:
$ref: '#/definitions/ViewAsRequest'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AccessTokenResponse'
'400':
description: invalid credentials
definitions:
AppOauthConnectionStatus:
type: object
required:
- connected
properties:
connected:
type: boolean
description: whether an org-level OAuth token is currently connected
connectedAt:
type: string
description: when the org-level token was issued, if connected
example: '2017-01-24T13:57:52Z'
connectedById:
type: string
description: id of the user who set up the org-level connection, if connected
RevokeAppOauthTokensRequest:
type: object
required:
- tokenIds
properties:
tokenIds:
type: array
description: ids of the oauth tokens to revoke
items:
type: string
EmailRequest:
type: object
required:
- email
properties:
email:
type: string
description: email address
example: example@example.com
AppOauthUserConnection:
type: object
required:
- tokenId
- userId
- issuedAt
properties:
tokenId:
type: string
description: the oauth token id, used to revoke the connection
userId:
type: string
description: the id of the user who authorized
issuedAt:
type: string
description: when the connection was authorized
example: '2017-01-24T13:57:52Z'
activeAt:
type: string
description: when the connection was last used for an API call
example: '2017-01-24T13:57:52Z'
AccessTokenRequest:
type: object
required:
- idToken
- scope
properties:
idToken:
type: string
description: id token
scope:
type: string
description: scope being requested
fromToken:
type: string
description: an existing token
clientId:
type: string
description: client id for OAuth2.0 PKCE
codeChallenge:
type: string
description: code_challenge for OAuth2.0 PKCE
codeChallengeMethod:
type: string
description: code_challenge_method for OAuth2.0 PKCE
redirectUri:
type: string
description: redirect_uri for OAuth2.0 PKCE
IdpAccessTokenResponse:
type: object
required:
- id_token
properties:
id_token:
type: string
description: id token value (likely a JWT)
example: header.payload.signature
AccessTokenResponse:
type: object
required:
- access_token
- expires_in
properties:
access_token:
type: string
description: access token value
readOnly: true
example: 2YotnFZFEjr1zCsicMWsdv
token_type:
type: string
description: access token type
readOnly: true
example: bearer
expires_in:
type: integer
format: int32
description: expiration time of token, in seconds
readOnly: true
example: '86400'
refresh_token:
type: string
description: refresh token value
readOnly: true
example: tGzv3JOkF0XG5Qx2TlKWIA
scope:
type: string
description: scope of the access token
readOnly: true
example: admin
redirect_uri:
type: string
description: redirect uri of the access token
readOnly: true
example: com.charthop.mobile://oauth
ConnectUriResponse:
type: object
required:
- uri
properties:
uri:
type: string
description: uri to use for oath
example: https://api.tryfinch.com/connect/sessions
ViewAsRequest:
type: object
required:
- orgId
- scope
properties:
orgId:
type: string
description: org id
example: 588f7ee98f138b19220041a7
personId:
type: string
description: person id
example: 588f7ee98f138b19220041a7
userId:
type: string
description: user id
example: 588f7ee98f138b19220041a7
roleId:
type: string
description: role id
example: 588f7ee98f138b19220041a7
scope:
type: string
description: scope being requested
McpApproveRequest:
type: object
required:
- clientId
- redirectUri
- codeChallenge
- codeChallengeMethod
- resource
properties:
clientId:
type: string
redirectUri:
type: string
codeChallenge:
type: string
codeChallengeMethod:
type: string
resource:
type: string
state:
type: string
orgId:
type: string