# Receive SAML Callback

`POST /gate/saml/callback` · Identity & Access · Federation

Receives the SAML 2.0 `SAMLResponse` and `RelayState` from the identity provider after a sign-in started at `authorize`.

The whole response must be signed by the provider in its metadata, come from that provider's `entityID`, be addressed to this project's ACS URL, and answer the AuthnRequest in the state, once.

On success the gateway resolves or provisions the end user and redirects to the app's `redirectUri` with a single-use `code` in the fragment, valid for 60 seconds. The page gets a session from `POST /@{projectSlug}/gate/idp/exchange`.

Sign-in started at the identity provider isn't available for a project's end users.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `SAMLResponse` | string | yes | The base64-encoded SAML response the identity provider posted. Its signature, audience, validity window and `InResponseTo` are checked before the end user is signed in. |
| `RelayState` | string | no | The signed state the platform sent with the request, returned unchanged by the provider. Without a valid one, the sign-in is refused: a sign-in that starts at the identity provider is not accepted. |

```json
{
  "SAMLResponse": "string",
  "RelayState": "string"
}
```

## Responses


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_REQUEST_SHAPE` | The SAML callback body failed validation (a required field such as `SAMLResponse` is missing or malformed). |
| 502 | `K9O_IDP_FEDERATION_FAILED` | The SAML assertion could not be validated or the identity provider returned an unprocessable response. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/gate/saml/callback' \
  -H 'Content-Type: application/json' \
  -d '{
  "SAMLResponse": "string",
  "RelayState": "string"
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/gate/saml/callback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "SAMLResponse": "string",
  "RelayState": "string"
}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/identity-access/receive-saml-callback
