openapi: 3.0.3
info:
  description: |
    Anropet till API:et ska göras över HTTPS och skyddas med OAuth 2.0 Bearer token.
    Access token ska ha scope behorighetskontroll:read.

    Token-endpoint och detaljer för tokenhämtning hanteras separat och
    ingår inte i denna API-beskrivning.
  title: Attribute Provider (ATP) API
  version: "1.0"
servers:
- description: Produktionsmiljö
  url: https://api.example.se/v1
- description: Testmiljö
  url: https://api-test.example.se/v1
paths:
  /behorighetskontroll:
    post:
      description: |
        Kontrollerar om en person är behörig att begära information om verkliga huvudmän.
        *Notera: POST används i stället för GET för att undvika att en personlig identifieringsbeteckning (känslig data) loggas i URL‑en via queryparametrar.*
      operationId: kontrolleraBehorighet
      parameters:
      - description: Klientgenererat UUID för korrelation och felsökning. Vid fel
          kan samma värde returneras i fältet requestId eller i en response-header.
        in: header
        name: X-Request-Id
        required: true
        schema:
          example: f628a504-4631-4c04-8358-f17fc370ac79
          format: uuid
          type: string
      - description: Authorization token
        in: header
        name: Authorization
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              svenskPerson:
                summary: Svenskt personnummer
                value:
                  identitetsbeteckning: "197011129280"
              samordningsnummer:
                summary: Svenskt samordningsnummer
                value:
                  identitetsbeteckning: "197011629280"
              utlandskPerson:
                summary: Utländsk identitetsbeteckning
                value:
                  identitetsbeteckning: RSSMRA80A01H501U
            schema:
              $ref: "#/components/schemas/BehorighetskontrollRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                behorig:
                  summary: Personen är behörig
                  value:
                    behorig: true
                obehorig:
                  summary: Personen är inte behörig
                  value:
                    behorig: false
              schema:
                $ref: "#/components/schemas/BehorighetskontrollResponse"
          description: Behörighetskontroll genomförd.
        "400":
          content:
            application/problem+json:
              example:
                type: https://api.example.se/problems/invalid-request
                title: Felaktig begäran
                status: 400
                detail: identitetsbeteckning är obligatorisk.
                instance: /behorighetskontroll
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
          description: |
            Felaktig begäran, till exempel ogiltig eller saknad identitetsbeteckning.
        "401":
          content:
            application/problem+json:
              example:
                type: https://api.example.se/problems/unauthorized
                title: Obehörig
                status: 401
                detail: Saknad eller ogiltig access token.
                instance: /behorighetskontroll
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
          description: Saknad eller ogiltig Bearer token.
        "403":
          content:
            application/problem+json:
              example:
                type: https://api.example.se/problems/forbidden
                title: Åtkomst nekad
                status: 403
                detail: Access token saknar scope behorighetskontroll:read.
                instance: /behorighetskontroll
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
          description: Token saknar nödvändigt scope eller klienten saknar behörighet.
        "500":
          content:
            application/problem+json:
              example:
                type: https://api.example.se/problems/internal-server-error
                title: Internt serverfel
                status: 500
                detail: Ett oväntat fel inträffade.
                instance: /behorighetskontroll
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
          description: Internt serverfel.
      security:
      - OAuth2:
        - behorighetskontroll:read
      summary: Kontrollera behörighet för person
      tags:
      - Behorighetskontroll
components:
  parameters:
    RequestIdHeader:
      description: Klientgenererat UUID för korrelation och felsökning. Vid fel kan
        samma värde returneras i fältet requestId eller i en response-header.
      in: header
      name: X-Request-Id
      required: true
      schema:
        example: f628a504-4631-4c04-8358-f17fc370ac79
        format: uuid
        type: string
    AuthorizationHeader:
      description: Authorization token
      in: header
      name: Authorization
      required: true
      schema:
        type: string
  schemas:
    BehorighetskontrollRequest:
      additionalProperties: false
      example:
        identitetsbeteckning: "197011129280"
      properties:
        identitetsbeteckning:
          description: |
            Anger identiteten för den person som behörighetsförfrågan avser. Identitetsbeteckning kan vara personer inom EU/EES som har en notifierad e‑legitimation.
          example: "197011129280"
          maxLength: 50
          type: string
      required:
      - identitetsbeteckning
      type: object
    BehorighetskontrollResponse:
      additionalProperties: false
      example:
        behorig: true
      properties:
        behorig:
          description: Anger huruvida personen är behörig eller inte.
          example: true
          type: boolean
      required:
      - behorig
      type: object
    ApiErrorResponse:
      additionalProperties: true
      description: |
        Felmodell enligt RFC 9457, Problem Details for HTTP APIs, i linje med DIGG:s REST API-profil för felhantering.
      properties:
        type:
          description: |
            En URI-referens som identifierar problemtypen. Kan vara about:blank eller en URI till dokumentation för feltypen.
          example: https://api.example.se/problems/invalid-request
          format: uri-reference
          type: string
        title:
          description: "Kort, mänskligt läsbar sammanfattning av problemtypen."
          example: Felaktig begäran
          type: string
        status:
          description: HTTP-statuskod för felet.
          example: 400
          format: int32
          maximum: 599
          minimum: 100
          type: integer
        detail:
          description: "Kort beskrivning av det faktiska felet, avsedd för människa."
          example: identitetsbeteckning är obligatorisk.
          type: string
        instance:
          description: En URI-referens som identifierar den faktiska förekomsten av
            problemet.
          example: urn:behorighetskontroll/problems/f628a504-4631-4c04-8358-f17fc370ac79
          format: uri-reference
          type: string
      required:
      - status
      - title
      - type
      type: object
  securitySchemes:
    OAuth2:
      description: |
        OAuth 2.0 med grant type client_credentials. Access token skickas som Bearer token i Authorization-headern.
        Token-endpointen anges endast för att beskriva OAuth2-flödet. Detaljer för klientregistrering, mTLS och tokenhämtning hanteras separat.
        Token ska vara utfärdad till Bolagsverket efter autentisering med client_id, client_secret och klientcertifikat via mTLS. Endast klientcertifikat vars certifikatidentitet matchar den i förväg överenskomna identiteten ska accepteras av Authorization Server.
      flows:
        clientCredentials:
          scopes:
            behorighetskontroll:read: Läsbehörighet till behörighetskontroll.
          tokenUrl: https://auth.example.se/oauth2/token
      type: oauth2