{
  "openapi": "3.0.3",
  "info": {
    "title": "Nabla Connect Instance API",
    "description": "Reference for the Nabla Connect Instance API: the endpoints your backend calls on behalf of your Nabla Connect instance as a whole, rather than of one of the organizations linked to it.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://{region}.api.nabla.com/v1/connect/instance",
      "variables": {
        "region": {
          "enum": [
            "us",
            "eu"
          ],
          "default": "us",
          "description": "Geographical region where your Nabla Connect instance exists."
        }
      }
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "summary": "Authenticate your backend as your instance",
        "description": "Use this endpoint to get a medium-lived JWT access token for your backend to call the Instance API exposed by Nabla. Unlike an [Organization API access token](/connect/reference/oauth-generate-server-access-token), which is bound to one of the organizations linked to your Nabla Connect instance, this token is bound to the instance itself and only authenticates calls to the Instance API. The client assertion is the same as for the Organization API, with its `aud` set to this endpoint's URL. See the [Authentication](/connect/guides/authentication) guide for details on how to construct it.",
        "tags": [
          "Authentication"
        ],
        "operationId": "oauth-generate-instance-access-token",
        "x-unauthenticated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "description": "This endpoint only supports the 'client_credentials' value.",
                    "example": "client_credentials"
                  },
                  "client_assertion_type": {
                    "type": "string",
                    "description": "This endpoint only supports the 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' value.",
                    "example": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                  },
                  "client_assertion": {
                    "type": "string",
                    "description": "A short-lived JWT assertion that serves to authenticate this request, signed by an OAuth Client of your Nabla Connect instance."
                  }
                },
                "required": [
                  "grant_type",
                  "client_assertion_type",
                  "client_assertion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JWT access token that can be used to access the Instance API.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "$ref": "#/components/schemas/jwt_token"
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "The lifetime of the access token, in seconds."
                    }
                  },
                  "required": [
                    "access_token",
                    "expires_in"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/organizations/lookup-by-idp-groups": {
      "post": {
        "summary": "Find organizations from IdP groups",
        "description": "Returns the organizations linked to your Nabla Connect instance whose users are identified by at least one of the given identity provider (IdP) groups, as configured for SAML SSO (SAML or SCIM groups). Use it to find the organization to provision a user in from the groups your IdP reports for them, before you have any organization to authenticate as: this endpoint takes an [instance access token](/connect/reference/oauth-generate-instance-access-token). Organizations restricting access to none of these groups are not returned, so an empty list means no linked organization matches. Several organizations are returned when the groups match more than one.",
        "tags": [
          "Organizations"
        ],
        "operationId": "lookup-organizations-by-idp-groups",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/lookup_organizations_by_idp_groups_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The matching organizations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/lookup_organizations_by_idp_groups_response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "jwt_token": {
        "type": "string",
        "description": "An authentication token using the JWT serialization format. JWT tokens contain varying data (depending on their intended use) and use a signature to guarantee their authenticity.",
        "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwic3ViIjoiMTIzNDU2Nzg5MCIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMn0.v5qdy8w9Ygs5fdic9a1LuX76PUdx3omYd5GlDTAF3Ug"
      },
      "lookup_organizations_by_idp_groups_request": {
        "type": "object",
        "description": "The IdP groups to find organizations for.",
        "properties": {
          "idp_group_ids": {
            "type": "array",
            "description": "The identifiers of the user's groups, as your IdP sends them in the SAML assertion's groups attribute (for example group names for Okta, or group object IDs for Microsoft Entra ID). They are compared exactly (case and whitespace included) with the groups configured for the organizations, as the SAML sign-in compares them. Duplicates are ignored.",
            "minItems": 1,
            "maxItems": 1000,
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "idp_group_ids"
        ]
      },
      "uuid": {
        "type": "string",
        "format": "uuid",
        "description": "A unique identifier.",
        "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6"
      },
      "idp_groups_organization": {
        "type": "object",
        "description": "An organization matched by IdP groups.",
        "properties": {
          "organization_id": {
            "$ref": "#/components/schemas/uuid"
          },
          "matched_idp_group_ids": {
            "type": "array",
            "description": "The requested IdP group IDs that identify the organization's users.",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "organization_id",
          "matched_idp_group_ids"
        ]
      },
      "lookup_organizations_by_idp_groups_response": {
        "type": "object",
        "properties": {
          "organizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/idp_groups_organization"
            }
          }
        },
        "required": [
          "organizations"
        ]
      }
    }
  },
  "x-squad": "api"
}
