Hanko SAML API
The SAML API from Hanko — 3 operation(s) for saml.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hanko-saml-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
version: 1.2.0
title: Hanko Public SAML API
description: '## Introduction
This is the OpenAPI specification for the [Hanko Public API](https://github.com/teamhanko/hanko/blob/main/backend/README.md#basic-usage).
## Authentication
The API uses [JSON Web Tokens](https://www.rfc-editor.org/rfc/rfc7519.html) (JWTs) for authentication.
JWTs are verified using [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517) (JWK).
JWKs can be [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)
through the `secrets.keys` options. The API also publishes public cryptographic keys as a
[JWK set](https://www.rfc-editor.org/rfc/rfc7517#section-2) through the `.well-known/jwks.json` endpoint
to enable clients to verify token signatures.
JWTs must be provided on requests to protected endpoints using one of the following schemes:
### CookieAuth
**Security Scheme Type**: `API Key`
**Cookie parameter name**: `hanko`
The JWT must be provided in a Cookie with the name `hanko`.
### BearerTokenAuth
**Security Scheme Type**: `http`
**HTTP Authorization Scheme**: `Bearer`
**Bearer format**: `JWT`
The JWT must be provided in an HTTP Authorization header with bearer type: `Authorization: Bearer <JWT>`.
## Cross-Origin Resource Sharing
Cross-Origin Resource Sharing (CORS) can be currently
[configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)
for public endpoints via the `server.public.cors` options.
---
'
contact:
email: developers@hanko.io
license:
name: AGPL-3.0-or-later
url: https://www.gnu.org/licenses/agpl-3.0.txt
servers:
- url: https://{tenant_id}.hanko.io
variables:
tenant_id:
default: ''
description: The (UU)ID of a tenant. Replace the default value with your tenant ID.
tags:
- name: SAML
paths:
/saml/provider:
get:
deprecated: true
summary: Get a SAML provider
description: Get a SAML service provider config for a provided domain.
operationId: get-saml-provider
tags:
- SAML
parameters:
- name: domain
in: query
description: Fully qualified domain name for which a SAML service provider is registered
required: true
schema:
type: string
format: hostname
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
enabled:
type: boolean
readOnly: true
default: true
name:
type: string
readOnly: true
example: MySamlProvier
domain:
type: string
format: hostname
readOnly: true
example: text.example
metadata_url:
type: string
format: uri
readOnly: true
example: http://idp-metadata.url
skip_email_verification:
type: boolean
readOnly: true
default: false
attribute_map:
type: object
additionalProperties: false
properties:
name:
type: string
family_name:
type: string
given_name:
type: string
middle_name:
type: string
nickname:
type: string
preferred_username:
type: string
profile:
type: string
picture:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zone_info:
type: string
locale:
type: string
updated_at:
type: string
email:
type: string
email_verified:
type: string
phone:
type: string
phone_verified:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'404':
description: Not Found
/saml/metadata:
get:
summary: Get SAML Metadata
description: Download SAML service provider metadata or public certificate.
operationId: get-saml-metadata
tags:
- SAML
parameters:
- name: domain
in: query
description: Fully qualified domain name to which a SAML service provider is registered
required: true
schema:
type: string
- name: cert_only
in: query
description: Toggle to download the SAML service provider public certificate
schema:
type: boolean
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
'404':
description: Not found
/saml/callback:
post:
summary: SAML identity provider callback
description: Callback endpoint called by the identity provider after successful login.
operationId: post-saml-callback
tags:
- SAML
requestBody:
description: SAML Identity Provider Response
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
RelayState:
type: string
SAMLResponse:
type: string
responses:
'302':
description: Found
headers:
Set-Cookie:
schema:
type: string
description: Contains the JSON Web Token (JWT) that must be provided to protected endpoints.Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`.
X-Auth-Token:
schema:
type: string
description: Present only when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header`for purposes of cross-domain communication between client and Hanko API.
'307':
description: Temporary Redirect
headers:
Location:
schema:
type: string
description: On error, redirect to the `saml.default_redirect_url` set in the backend-configuration. Error details are provided in the location URL in the form of `error` and `error_description`query params.
components:
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Bad Request
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
securitySchemes:
CookieAuth:
type: apiKey
in: cookie
name: hanko
BearerTokenAuth:
type: http
scheme: bearer
bearerFormat: JWT
externalDocs:
description: More about Hanko
url: https://github.com/teamhanko/hanko