openapi: 3.0.2
info:
  title: ESP APIs
  version: 26.0.0
  description: >-
    ESP APIs provide authentication flows via SPID, CIE, CNS, and EIDAS. Use
    these endpoints to obtain a session key, initiate a login, and retrieve a
    JWT containing the user's identity attributes.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: Get Key
    description: >-
      Returns a session key (`authnKey`) to initiate an authentication flow with
      SPID, CIE, or EIDAS.
    externalDocs:
      description: Integration Guide — Get Key
      url: >-
        https://docs.namirial.app/products/esp/enterprise-documentation/developer-documentation/integration-guide/getkey
  - name: Login
    description: Initiates the authentication flow with SPID/EIDAS, CIE, or CNS.
    externalDocs:
      description: Integration Guide — Login
      url: >-
        https://docs.namirial.app/products/esp/enterprise-documentation/developer-documentation/integration-guide/login
  - name: Logout
    description: Initiates the SPID logout flow. Not required for Level 2 authentications.
    externalDocs:
      description: Integration Guide — Logout
      url: >-
        https://docs.namirial.app/products/esp/enterprise-documentation/developer-documentation/integration-guide/logout
  - name: Get user
    description: >-
      Exchanges the session `id` and `key` (returned after login) for a JWT
      containing the user's identity attributes.
    externalDocs:
      description: Integration Guide — Get user token
      url: >-
        https://docs.namirial.app/products/esp/enterprise-documentation/developer-documentation/integration-guide/token
paths:
  /sslprotected/{environment_name}/getKey.php:
    get:
      tags:
        - Get Key
      summary: Get a authn key to start an authentication flow
      deprecated: true
      security:
        - sslCertificate: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: level
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          required: false
          description: 'Authentication level. Accepted values: 1, 2, 3.'
          example: 2
        - in: query
          name: attributes
          schema:
            type: string
            enum:
              - Base
              - Full
          required: true
          description: 'Attribute set to request. Accepted values: `Base`, `Full`.'
          example: Full
      responses:
        '200':
          description: The authn key
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/GetKeyResponse'
        '400':
          description: The input parameters are missing or invalid
        '403':
          description: The SSL certificate is missing or invalid
      operationId: getKeyDeprecatedPhp
  /sslprotected/{environment_name}/getKey:
    get:
      tags:
        - Get Key
      summary: Get a authn key to start an authentication flow
      deprecated: true
      security:
        - sslCertificate: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: The integration name provided to the customer
          example: myintegration
        - in: query
          name: level
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          required: false
          description: 'Authentication level. Accepted values: 1, 2, 3.'
          example: 2
        - in: query
          name: attributes
          schema:
            type: string
            enum:
              - Base
              - Full
          required: true
          description: 'Attribute set to request. Accepted values: `Base`, `Full`.'
          example: Full
        - in: query
          name: spidType
          schema:
            type: string
            enum:
              - P
              - LP
              - PG
              - PF
              - PX
          required: false
          description: SPID SAML Purpose value. Applies to SPID authentication only.
          example: P
      responses:
        '200':
          description: The authn key
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/GetKeyResponse'
        '400':
          description: The input parameters are missing or invalid
        '403':
          description: The SSL certificate is missing or invalid
      operationId: getKeyDeprecated
  /api/secure/{environment_name}/getKey:
    get:
      tags:
        - Get Key
      summary: Get a authn key to start an authentication flow
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: level
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          required: false
          description: 'Authentication level. Accepted values: 1, 2, 3.'
          example: 2
        - in: query
          name: attributes
          schema:
            type: string
            enum:
              - Base
              - Full
          required: true
          description: 'Attribute set to request. Accepted values: `Base`, `Full`.'
          example: Full
        - in: query
          name: spidType
          schema:
            type: string
            enum:
              - P
              - LP
              - PG
              - PF
              - PX
          required: false
          description: SPID SAML Purpose value. Applies to SPID authentication only.
          example: P
      responses:
        '200':
          description: The authn key
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GetKeyResponse'
        '400':
          description: The input parameters are missing or invalid
        '401':
          description: Unauthorized. The API key is missing or invalid.
        '403':
          description: Forbidden error
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/responses/ApiKeyError'
        '404':
          description: Environment not found.
      operationId: getKey
  /{environment_name}/spidlogin.php:
    get:
      tags:
        - Login
      summary: Login with SPID with a browser
      deprecated: true
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: level
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          required: false
          description: 'Authentication level. Accepted values: 1, 2, 3.'
          example: 2
        - in: query
          name: attributes
          schema:
            type: string
            enum:
              - Base
              - Full
          required: true
          description: 'Attribute set to request. Accepted values: `Base`, `Full`.'
          example: Full
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            It's the redirect url called at the end of the authentication
            process (It should be communicated during the assessment phase)
          example: http://localhost
        - in: query
          name: authnKey
          schema:
            type: string
          required: true
          description: The authn key obtained from the getKey endpoint
          example: >-
            c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
      responses:
        '200':
          description: >-
            Redirects the browser to the identity provider login page. After
            successful authentication, the user is redirected to the final URL
            with `sessionid` and `sessionkey` query parameters. Pass them to the
            Get user token endpoint to retrieve the JWT.
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidFinal'
                  - $ref: '#/components/responses/InvalidLevel'
                  - $ref: '#/components/responses/InvalidAttributes'
                  - $ref: '#/components/responses/GenericAuthError'
                  - $ref: '#/components/responses/RedirectUriMissing'
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidAuthnKey'
                  - $ref: '#/components/responses/AuthnKeyMismatch'
                  - $ref: '#/components/responses/MissingAuthnKey'
                  - $ref: '#/components/responses/UnderLevel'
                  - $ref: '#/components/responses/LevelMismatch'
                  - $ref: '#/components/responses/CurrentSessionLevel'
      security: []
      operationId: spidLoginDeprecatedPhp
  /{environment_name}/cielogin.php:
    get:
      tags:
        - Login
      summary: Login with CIE with a browser
      deprecated: true
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: level
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
            default: 1
          required: false
          description: 'Authentication level. Accepted values: 1, 2, 3.'
          example: 2
        - in: query
          name: attributes
          schema:
            type: string
            enum:
              - Base
              - Full
          required: true
          description: 'Attribute set to request. Accepted values: `Base`, `Full`.'
          example: Full
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            Redirect URL called at the end of the authentication process.
            Provided during the assessment phase.
          example: http://localhost
        - in: query
          name: authnKey
          schema:
            type: string
          required: true
          description: The authn key obtained from the getKey endpoint
          example: >-
            c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
      responses:
        '200':
          description: >-
            Redirects the browser to the identity provider login page. After
            successful authentication, the user is redirected to the final URL
            with `sessionid` and `sessionkey` query parameters. Pass them to the
            Get user token endpoint to retrieve the JWT.
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidFinal'
                  - $ref: '#/components/responses/InvalidLevel'
                  - $ref: '#/components/responses/InvalidAttributes'
                  - $ref: '#/components/responses/GenericAuthError'
                  - $ref: '#/components/responses/RedirectUriMissing'
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidAuthnKey'
                  - $ref: '#/components/responses/AuthnKeyMismatch'
                  - $ref: '#/components/responses/MissingAuthnKey'
                  - $ref: '#/components/responses/UnderLevel'
                  - $ref: '#/components/responses/LevelMismatch'
                  - $ref: '#/components/responses/CurrentSessionLevel'
      security: []
      operationId: cieLoginDeprecatedPhp
  /{environment_name}/spidlogin:
    get:
      tags:
        - Login
      summary: Login with SPID/EIDAS with a browser
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: reference
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{1,50}$
            maxLength: 50
          required: false
          description: Client reference for billing purposes.
          example: mycustomer
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            Redirect URL called at the end of the authentication process.
            Provided during the assessment phase.
          example: http://localhost
        - in: query
          name: authnKey
          schema:
            type: string
          required: true
          description: The authn key obtained from the getKey endpoint
          example: >-
            c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
      responses:
        '200':
          description: >-
            Redirects the browser to the identity provider login page. After
            successful authentication, the user is redirected to the final URL
            with `sessionid` and `sessionkey` query parameters. Pass them to the
            Get user token endpoint to retrieve the JWT.
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidParameter'
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/SSLError'
      security: []
      operationId: spidLogin
  /{environment_name}/cielogin:
    get:
      tags:
        - Login
      summary: Login with CIE with a browser
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            Redirect URL called at the end of the authentication process.
            Provided during the assessment phase.
          example: http://localhost
        - in: query
          name: authnKey
          schema:
            type: string
          required: true
          description: The authn key obtained from the getKey endpoint
          example: >-
            c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
      responses:
        '200':
          description: >-
            Redirects the browser to the identity provider login page. After
            successful authentication, the user is redirected to the final URL
            with `sessionid` and `sessionkey` query parameters. Pass them to the
            Get user token endpoint to retrieve the JWT.
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidParameter'
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/SSLError'
      security: []
      operationId: cieLogin
  /{environment_name}/cnslogin:
    get:
      tags:
        - Login
      summary: Login with CNS with a browser
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            Redirect URL called at the end of the authentication process.
            Provided during the assessment phase.
          example: http://localhost
        - in: query
          name: authnKey
          schema:
            type: string
          required: true
          description: The authn key obtained from the getKey endpoint
          example: >-
            c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
      responses:
        '200':
          description: >-
            Redirects the browser to the identity provider login page. After
            successful authentication, the user is redirected to the final URL
            with `sessionid` and `sessionkey` query parameters. Pass them to the
            Get user token endpoint to retrieve the JWT.
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidParameter'
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/SSLError'
      security: []
      operationId: cnsLogin
  /{environment_name}/logout:
    get:
      tags:
        - Logout
      summary: Logout for SPID
      description: >-
        Initiates the SPID logout flow. Not required for Level 2
        authentications.
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: The integration name provided to the customer
          example: myintegration
        - in: query
          name: final
          schema:
            type: string
          required: true
          description: >-
            Redirect URL called at the end of the authentication process.
            Provided during the assessment phase.
          example: http://localhost
      responses:
        '200':
          description: Logout successful
        '400':
          description: Wrong parameters
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidParameter'
      security: []
      operationId: logout
  /sslprotected/{environment_name}/getUser.php:
    get:
      tags:
        - Get user
      summary: Get a user JWT
      deprecated: true
      security:
        - sslCertificate: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: ID
          schema:
            type: string
          required: true
          description: The ESP user identifier
          example: _ecf182c0024338b109397ea3d04ab141
        - in: query
          name: key
          schema:
            type: string
          required: true
          description: The ESP session key
          example: _029da15302d1f7bf8a4ff9826b4489c3
      responses:
        '200':
          description: The authn key
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/JWTBearerResponse'
        '400':
          description: missing key or ID parameter
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/SSLError'
                  - $ref: '#/components/responses/KeyIdNotFound'
      operationId: getUserDeprecatedPhp
  /sslprotected/{environment_name}/getUser:
    get:
      tags:
        - Get user
      summary: Get a user JWT
      deprecated: true
      security:
        - sslCertificate: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: ID
          schema:
            type: string
          required: true
          description: The ESP user identifier
          example: _ecf182c0024338b109397ea3d04ab141
        - in: query
          name: key
          schema:
            type: string
          required: true
          description: The ESP session key
          example: _029da15302d1f7bf8a4ff9826b4489c3
      responses:
        '200':
          description: The authn key
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/JWTBearerResponse'
        '400':
          description: missing key or ID parameter
        '403':
          description: Forbidden error
          content:
            text/html:
              schema:
                oneOf:
                  - $ref: '#/components/responses/SSLError'
                  - $ref: '#/components/responses/KeyIdNotFound'
      operationId: getUserDeprecated
  /api/secure/{environment_name}/getUser:
    get:
      tags:
        - Get user
      summary: Get a user JWT
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: environment_name
          schema:
            type: string
          required: true
          description: >-
            The environment path provided by Namirial during the assessment
            phase
          example: myintegration
        - in: query
          name: sessionid
          schema:
            type: string
          required: true
          description: >-
            The user identifier returned as a query parameter in the redirect to
            the final URL after login.
          example: _ecf182c0024338b109397ea3d04ab141
        - in: query
          name: sessionkey
          schema:
            type: string
          required: true
          description: >-
            The session key returned as a query parameter in the redirect to the
            final URL after login.
          example: _029da15302d1f7bf8a4ff9826b4489c3
      responses:
        '200':
          description: JWT containing the user's SAML assertion attributes
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/JWTBearerResponse'
        '400':
          description: missing key or ID parameter
        '401':
          description: Unauthorized. The API key is missing or invalid.
        '403':
          description: Forbidden error
          content:
            text/plain:
              schema:
                oneOf:
                  - $ref: '#/components/responses/ApiKeyError'
                  - $ref: '#/components/responses/KeyIdNotFound'
        '404':
          description: Environment not found.
      operationId: getUser
externalDocs:
  description: Official ESP documentation
  url: https://docs.namirial.app/products/esp/homepage
servers:
  - url: https://esp-saas.test.namirialtsp.com
    description: Development and testing environment
  - url: https://esp-saas.namirialtsp.com
    description: Production environment
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Esp-Api-Key
    sslCertificate:
      type: apiKey
      in: header
      name: X-SSL-Client-Cert
      description: >-
        Mutual TLS (mTLS) authentication. A client SSL certificate issued by
        Namirial during the assessment phase is required. The certificate must
        be presented during the TLS handshake.
  responses:
    InvalidParameter:
      description: Invalid Request Parameter
    InvalidLevel:
      description: Error code 2 - Invalid level parameter
    InvalidAttributes:
      description: Error code 3 - Invalid attributes parameter
    InvalidAuthnKey:
      description: Error code 4 - Invalid authn key
    AuthnKeyMismatch:
      description: Error code 5 - The authn key has a mismatch with the SP configuration
    MissingAuthnKey:
      description: Error code 6 - The authn key is missing
    GenericAuthError:
      description: Error code 7/8 - Generic authentication error
    RedirectUriMissing:
      description: Error code 9 - The SP redirect uri misses into the configuration
    UnderLevel:
      description: >-
        Error code 10 - The authentication level obtained from lower SPID to
        what is requested through authnKey
    LevelMismatch:
      description: >-
        Error code 11 - There is a level mismatch between requested level and
        authn key level
    CurrentSessionLevel:
      description: >-
        Error code 12 - The authentication level of a SPID session already
        active not corresponding to the currently requested level
    KeyIdNotFound:
      description: Error code 3 - The session is missing for input key and ID parameters
    SSLError:
      description: SSL authentication error
    ApiKeyError:
      description: ApiKey authentication error
    InvalidFinal:
      description: Error code 1 - Invalid final url
  schemas:
    GetKeyResponse:
      type: string
      example: >-
        c1BUQkJ4d3hYUWV6ZEQ4TktlSWV6ZmozVy9HNzNrQlcyRFlvMTB1TTlGKzE3dWNjdHNLV2RUN0pVNTNJQnhsVnNMMWhBS0lucGNxMC9qY0c3U3BWYlc5dktOMXFvVkhyYUIrdDFBd1VBWGM5bERzS1RnVzd1V251R3pWUEpiUmc
    JWTBearerResponse:
      type: string
      description: >-
        A signed JWT containing the user's SAML assertion attributes. The claims
        vary by identity scheme (SPID vs CIE). See [Get user
        token](https://docs.namirial.app/products/esp/enterprise-documentation/developer-documentation/integration-guide/token)
        for decoded examples.
security:
  - ApiKeyAuth: []
