---
updatedAt: 2026-05-27T18:07:25.000Z
agentTools:
  projectIndex: https://developer.ironcladapp.com/llms.txt
---

# Initiate an Authorization Transaction

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).

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Ironclad OAuth 2.0 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://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"
    }
  ],
  "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "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"
        }
      },
      "ClientId": {
        "name": "client_id",
        "in": "query",
        "description": "The client ID of the client application issued at registration.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "6013609108b8f070cee94fc1"
        }
      },
      "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"
        }
      },
      "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"
        }
      },
      "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"
        }
      }
    }
  },
  "tags": [
    {
      "name": "Authorization",
      "description": "OAuth 2.0 authorization endpoints for token management and user authentication."
    }
  ],
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-languages": [
      "curl",
      "node",
      "ruby",
      "javascript",
      "python"
    ]
  }
}
```