openapi: 3.2.0
info:
  title: Access Authorization Grants API
  version: 0.1.0
  description: 'The Authorization Grant Manager provides APIs for creating, managing, and retrieving authorization documents, authorization grants, and authorization requests used within Elhub''s access control ecosystem.

    Note: The authorization-grant APIs are under active development. Schemas and parameters may still change.'
  x-status: Development
  contact:
    name: team-devxp
  license:
    name: MIT
    url: https://github.com/elhub/auth-grant-manager?tab=MIT-1-ov-file
servers:
- url: https://api.elhub.no
  description: Production
- url: https://api-mt1.elhub.no
  description: MT1
security:
- bearerAuth: []
tags:
- name: Authorization Grants
  description: Operations for listing and retrieving authorization grants and their scopes.
paths:
  /access/v0/authorization-grants:
    get:
      tags:
      - Authorization Grants
      summary: List authorization grants
      operationId: listV0AuthorizationGrants
      description: Retrieve a list of authorization grants available to the caller. The result is constrained by the caller's token and GLN context. Results are returned ordered by createdAt DESC (newest first) and support offset-based pagination.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/AuthorizationMaskinportenOrEndUser'
      - $ref: '#/components/parameters/SenderGlnOptional'
      - $ref: '#/components/parameters/OnBehalfOfGlnOptional'
      - name: page[number]
        in: query
        required: false
        description: Zero-based page number. Defaults to 0.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: page[size]
        in: query
        required: false
        description: Number of items per page. Defaults to 100, maximum 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      responses:
        '200':
          description: A list of authorization grants.
          content:
            application/vnd.api+json:
              schema:
                $ref: ./schemas/grants/authorization-grant-collection.schema.json
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401UnauthorizedError'
        '403':
          $ref: '#/components/responses/403ForbiddenError'
        '406':
          $ref: '#/components/responses/406NotAcceptableError'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /access/v0/authorization-grants/{id}:
    get:
      tags:
      - Authorization Grants
      summary: Get authorization grant by id
      operationId: getV0AuthorizationGrant
      description: Retrieve a specific authorization grant by its identifier.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/AuthorizationMaskinportenOrEndUserOptional'
      - $ref: '#/components/parameters/SenderGlnOptional'
      - $ref: '#/components/parameters/OnBehalfOfGlnOptional'
      - name: id
        in: path
        required: true
        description: Unique identifier of the authorization grant to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: The requested authorization grant.
          content:
            application/vnd.api+json:
              schema:
                $ref: ./schemas/grants/authorization-grant-resource.schema.json
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401UnauthorizedError'
        '404':
          $ref: '#/components/responses/404NotFoundError'
        '406':
          $ref: '#/components/responses/406NotAcceptableError'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
      - Authorization Grants
      summary: Update authorization grant status
      operationId: updateV0AuthorizationGrant
      description: Update the status of an authorization grant. This endpoint is intended for internal Elhub systems (BRS) and is not available to external integrators.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - name: id
        in: path
        required: true
        description: Unique identifier of the authorization grant to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: ./schemas/grants/authorization-grant-update.schema.json
      responses:
        '200':
          description: The authorization grant was successfully updated.
          content:
            application/vnd.api+json:
              schema:
                $ref: ./schemas/grants/authorization-grant-resource.schema.json
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401UnauthorizedError'
        '403':
          $ref: '#/components/responses/403ForbiddenError'
        '404':
          $ref: '#/components/responses/404NotFoundError'
        '406':
          $ref: '#/components/responses/406NotAcceptableError'
        '409':
          $ref: '#/components/responses/409ConflictError'
        '422':
          $ref: '#/components/responses/422UnprocessableEntityError'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /access/v0/authorization-grants/{id}/scopes:
    get:
      tags:
      - Authorization Grants
      summary: List scopes for authorization grant
      operationId: listV0AuthorizationGrantScopes
      description: Retrieve all scopes associated with a specific authorization grant.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/AuthorizationMaskinportenOrEndUser'
      - $ref: '#/components/parameters/SenderGlnOptional'
      - $ref: '#/components/parameters/OnBehalfOfGlnOptional'
      - name: id
        in: path
        required: true
        description: Unique identifier of the authorization grant whose scopes should be retrieved.
        schema:
          type: string
      responses:
        '200':
          description: A list of authorization scopes associated with the grant.
          content:
            application/vnd.api+json:
              schema:
                $ref: ./schemas/grants/authorization-scope-collection.schema.json
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401UnauthorizedError'
        '403':
          $ref: '#/components/responses/403ForbiddenError'
        '404':
          $ref: '#/components/responses/404NotFoundError'
        '406':
          $ref: '#/components/responses/406NotAcceptableError'
        '409':
          $ref: '#/components/responses/409ConflictError'
        '500':
          $ref: '#/components/responses/500InternalServerError'
components:
  parameters:
    UserAgent:
      name: User-Agent
      in: header
      required: true
      schema:
        type: string
    SenderGlnOptional:
      name: SenderGln
      in: header
      required: false
      description: GLN of the party issuing the request.
      schema:
        type: string
    AuthorizationMaskinportenOrEndUser:
      name: Authorization
      in: header
      required: true
      description: 'Bearer token identifying the caller. This can be either a Maskinporten token or an end-user token, depending on the endpoint.

        '
      schema:
        type: string
    AuthorizationMaskinportenOrEndUserOptional:
      name: Authorization
      in: header
      required: false
      description: 'Optional bearer token identifying the caller. This can be either a Maskinporten token or an end-user token, depending on the endpoint.

        '
      schema:
        type: string
    OnBehalfOfGlnOptional:
      name: OnBehalfOfGln
      in: header
      required: false
      description: 'GLN of the organization on whose behalf the sender is acting, used in delegated Maskinporten flows.

        '
      schema:
        type: string
  responses:
    422UnprocessableEntityError:
      description: 'Unprocessable Entity. The request was well-formed but could not be followed due to semantic errors.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            unprocessableEntity:
              summary: Unprocessable entity error example
              value:
                errors:
                - status: '422'
                  title: Unprocessable Entity
                  detail: The request could not be processed due to semantic errors.
                meta:
                  createdAt: '2025-12-17T12:51:57+01:00'
            unsupportedDocumentType:
              summary: Unsupported document type
              value:
                errors:
                - status: '422'
                  title: Unsupported document type
                  detail: The authorization document type is not currently supported.
                meta:
                  createdAt: '2025-12-17T12:51:57+01:00'
            unsupportedRequestType:
              summary: Unsupported request type
              value:
                errors:
                - status: '422'
                  title: Unsupported request type
                  detail: The authorization request type is not currently supported.
                meta:
                  createdAt: '2025-12-17T12:51:57+01:00'
    406NotAcceptableError:
      description: 'Not Acceptable. The server cannot produce a response matching the list of acceptable values defined in the request''s proactive content negotiation headers.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            notAcceptable:
              summary: Not acceptable error example
              value:
                errors:
                - status: '406'
                  title: Not Acceptable
                  detail: The requested media type is not supported.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    400BadRequestError:
      description: 'Bad request. The request body is invalid or missing required fields.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            badRequest:
              summary: Bad request error example
              value:
                errors:
                - status: '400'
                  title: Bad Request
                  detail: A required field is missing or invalid.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    500InternalServerError:
      description: 'Internal server error. An unexpected error occurred while processing the request.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            internalServerError:
              summary: Internal server error example
              value:
                errors:
                - status: '500'
                  title: Internal Server Error
                  detail: An unexpected error occurred.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    409ConflictError:
      description: 'Conflict. The request could not be completed due to a conflict with the current state of the resource.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            conflict:
              summary: Conflict error example
              value:
                errors:
                - status: '409'
                  title: Conflict
                  detail: An authorization document already exists for the specified parties and validity period.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    404NotFoundError:
      description: 'Not found. The requested resource does not exist or is not accessible to the caller.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            notFound:
              summary: Not found error example
              value:
                errors:
                - status: '404'
                  title: Not Found
                  detail: The requested resource could not be found.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    401UnauthorizedError:
      description: 'Unauthorized. The caller is not authenticated or the provided token is invalid or expired.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            unauthorized:
              summary: Unauthorized error example
              value:
                errors:
                - status: '401'
                  title: Unauthorized
                  detail: Authentication credentials are missing or invalid.
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
    403ForbiddenError:
      description: 'Forbidden. The caller is authenticated but does not have permission to perform this operation.

        '
      content:
        application/vnd.api+json:
          schema:
            $ref: ./schemas/json-api-error.schema.json
          examples:
            forbidden:
              summary: Forbidden error example
              value:
                errors:
                - status: '403'
                  title: Forbidden
                  detail: A detailed description for getting forbidden
                  meta:
                    createdAt: '2025-12-17T12:51:57+01:00'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT