openapi: 3.1.0
info:
  title: Ironclad OAuth 2.0 Authorization API
  description: Documentation for Ironclad's OAuth 2.0 Implementation. More details on the [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749).
  version: '1'
  contact:
    name: Ironclad Support
    email: support@ironcladapp.com
servers:
- url: https://na1.ironcladapp.com/oauth
  description: Production server
- url: https://eu1.ironcladapp.com/oauth
  description: EU Production server
- url: https://demo.ironcladapp.com/oauth
  description: Demo server
tags:
- name: Authorization
  description: OAuth 2.0 authorization endpoints for token management and user authentication.
paths:
  /authorize:
    get:
      summary: Initiate an Authorization Transaction
      description: This endpoint is used to request authorization from a user to access their Ironclad data on their behalf. This is the initial request of an Authorization Code grant flow. The client application generally initiates the authorization flow, where a user will be redirected to Ironclad to log in and grant the requested permissions. The user is then redirected back to the client application redirect URI with an authorization code. See endpoint [specification](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1).
      operationId: oauth-authorize
      tags:
      - Authorization
      parameters:
      - $ref: '#/components/parameters/AuthCodeResponseType'
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/RedirectUri'
      - $ref: '#/components/parameters/ResourceScope'
      - $ref: '#/components/parameters/State'
      responses:
        '302':
          description: If the request is successful, the user will be directed to Ironclad to log in and grant permissions. Then the user will be redirected back to the client application redirect URI with an authorization code. If the user denies the request, they will be redirected back to the client application redirect URI with an error of 'access_denied'. If the request includes an invalid scope, the user will be redirected back to the client application redirect URI with an error of 'invalid_scope'.
          headers:
            Location:
              schema:
                type: string
                example: https://myapp.com/oauth/callback?code=63d415e0dd0d828c3a878548&state=1234567890
        '400':
          description: If the request is missing required parameters or has invalid parameters, the client will receive an 'invalid_request' response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_request
                  error_description:
                    type: string
                    example: 'Invalid or missing parameters: Invalid value for client_id, expected type UUID'
        '403':
          description: If the client application is not authorized to use a specific grant type, the client will receive an 'unauthorized_client' response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: unauthorized_client
                  error_description:
                    type: string
                    example: client not authorized to use this oauth grant type
  /token:
    post:
      summary: Request a Token
      description: This endpoint is used to request a token from the authorization server. If requesting an initial token in the Authorization Code grant, an authorization code, client ID, and client secret must be provided. If requesting to refresh an existing token in the Authorization Code grant, a refresh token, client ID, and client secret must be provided. If requesting a token via the Client Credentials grant, a client ID and secret must be provided. See endpoint [specification](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2).
      operationId: oauth-token
      tags:
      - Authorization
      parameters:
      - $ref: '#/components/parameters/ClientAuthorization'
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestBody'
      responses:
        '200':
          description: A successful response will return the relevant token details.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AuthorizationCodeGrantTokenResponse'
                - $ref: '#/components/schemas/ClientCredentialsGrantTokenResponse'
        '400':
          description: If the request is missing required parameters or has invalid parameters, the client will receive either an 'invalid_request' or 'invalid_scope' response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_request
                  error_description:
                    type: string
                    example: missing redirect uri
        '401':
          description: If the client associated with the initial authorization request does not match the client requesting the token or if the client associated with a token does not match the client requesting a token refresh, the client will receive an 'invalid_client' response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_client
                  error_description:
                    type: string
                    example: invalid client
        '403':
          description: If the client is not authorized to use a particular grant, the client will receive an 'unauthorized_client' response. If the request includes an invalid authorization code, an invalid refresh token, or an invalid redirect URI, the client will receive an 'invalid_grant' response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_grant
                  error_description:
                    type: string
                    example: authorization code has expired
components:
  parameters:
    State:
      name: state
      in: query
      description: An opaque value used by the client application to maintain state between the request and callback. The authorization server includes this value when redirecting the user back to the client application.
      required: false
      schema:
        type: string
        example: '1234567890'
    AuthCodeResponseType:
      name: response_type
      in: query
      description: The expected response type for the request. Must be set to 'code' for the Authorization Code grant.
      required: true
      schema:
        type: string
        enum:
        - code
        example: code
    RedirectUri:
      name: redirect_uri
      in: query
      description: The client applications redirect URI. Must be registered on the client application and consistent throughout the authorization transaction.
      required: true
      schema:
        type: string
        example: https://myapp.com/oauth/callback
    ClientId:
      name: client_id
      in: query
      description: The client ID of the client application issued at registration.
      required: true
      schema:
        type: string
        example: 6013609108b8f070cee94fc1
    ClientAuthorization:
      name: Authorization
      in: header
      description: The client ID and client secret of the client application in the format 'Basic <client_id:client_secret>' where client ID and secret are base64 encoded. Required if not provided in the request body.
      required: false
      schema:
        type: string
        example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
    ResourceScope:
      name: scope
      in: query
      description: Specifies the level of access that your client application is requesting. It should be a space-separated string of Ironclad resource scopes that can be found on the client application registration page. The scopes requested must be equal to or a subset of the client application’s registered scopes.
      required: false
      schema:
        type: string
        example: public.records.readRecords public.records.createRecords
  schemas:
    AuthorizationCodeGrantTokenResponse:
      description: Response for an Authorization Code grant token request. Will include the token scope if scope was requested.
      type: object
      properties:
        token_type:
          type: string
          example: Bearer
        access_token:
          type: string
          example: 63d415e0dd0d828c3a878548
        refresh_token:
          type: string
          example: 42353hj5hj453lhgff245323
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
          example: public.workflows.readWorkflows public.workflows.createWorkflows
      required:
      - token_type
      - access_token
      - refresh_token
      - expires_in
    ClientCredentialsGrantTokenResponse:
      description: Response for an Client Credentials grant token request. Will include the token scope if scope was requested.
      type: object
      properties:
        token_type:
          type: string
          example: Bearer
        access_token:
          type: string
          example: 63d415e0dd0d828c3a878548
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
          example: public.workflows.readWorkflows public.workflows.createWorkflows
      required:
      - token_type
      - access_token
      - expires_in
  requestBodies:
    TokenRequestBody:
      content:
        application/json:
          schema:
            oneOf:
            - type: object
              properties:
                grant_type:
                  description: The grant type for the request. Must be set to 'authorization_code' for the Authorization Code grant initial token request.
                  type: string
                  enum:
                  - authorization_code
                  example: authorization_code
                code:
                  description: The authorization code received from the authorization server.
                  type: string
                  example: 63d415e0dd0d828c3a878548
                redirect_uri:
                  description: The client applications redirect URI. Must be registered on the client application and consistent throughout the authorization transaction.
                  type: string
                  example: https://myapp.com/oauth/callback
                client_id:
                  description: The client ID of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 6013609108b8f070cee94fc1
                client_secret:
                  description: The client secret of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 346423435cdsfad786578adf
              required:
              - grant_type
              - code
              - redirect_uri
            - type: object
              properties:
                grant_type:
                  description: The grant type for the request. Must be set to 'refresh_token' for the Authorization Code grant refresh token request.
                  type: string
                  enum:
                  - refresh_token
                  example: refresh_token
                refresh_token:
                  description: The refresh token received from the authorization server for the access token being refreshed.
                  type: string
                  example: 63d415e0dd0d828c3a878548
                scope:
                  description: Specifies the level of access that your client application is requesting. It should be a space-separated string of Ironclad resource scopes that can be found on the client application registration page. The scopes requested must be equal to or a subset of the client application’s registered scopes and the previously granted scopes. When ommitted, the previously granted scopes are used.
                  type: string
                  example: public.workflows.readWorkflows public.workflows.createWorkflows
                client_id:
                  description: The client ID of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 6013609108b8f070cee94fc1
                client_secret:
                  description: The client secret of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 346423435cdsfad786578adf
              required:
              - grant_type
              - refresh_token
            - type: object
              properties:
                grant_type:
                  description: The grant type for the request. Must be set to 'client_credentials' for the Client Credentials grant token request.
                  type: string
                  enum:
                  - client_credentials
                  example: client_credentials
                scope:
                  description: Specifies the level of access that your client application is requesting. It should be a space-separated string of Ironclad resource scopes that can be found on the client application registration page. The scopes requested must be equal to or a subset of the client application’s registered scopes.
                  type: string
                  example: public.workflows.readWorkflows public.workflows.createWorkflows
                client_id:
                  description: The client ID of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 6013609108b8f070cee94fc1
                client_secret:
                  description: The client secret of the client application issued at registration. Required if not provided in the Authorization header.
                  type: string
                  example: 346423435cdsfad786578adf
              required:
              - grant_type
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
  samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python