openapi: 3.0.3
info:
  title: SWITCH edu-ID OpenID Connect (UZH Federated Identity) Discovery OAuth2 API
  description: OpenID Connect / OAuth 2.0 provider operated by SWITCH edu-ID and used by the University of Zurich as its central federated identity. This OpenAPI document is derived faithfully from the published OpenID Connect Discovery document at https://login.eduid.ch/.well-known/openid-configuration and the matching JWKS endpoint. Only endpoints, parameters, scopes, and claims actually advertised by the discovery document are represented here. Authorization Code flow with PKCE (S256) is the supported interactive flow; refresh_token is supported for token renewal.
  version: '2026-06-03'
  contact:
    name: SWITCH edu-ID
    url: https://login.eduid.ch/
  x-uzh-usage: UZH services rely on SWITCH edu-ID for SAML/Shibboleth and OpenID Connect authentication. See https://www.zi.uzh.ch/en/support/identity-access/eduid-faq.html
servers:
- url: https://login.eduid.ch
  description: SWITCH edu-ID production issuer
tags:
- name: OAuth2
  description: Authorization and token issuance
paths:
  /idp/profile/oidc/authorize:
    get:
      tags:
      - OAuth2
      operationId: authorize
      summary: Authorization endpoint
      description: Initiates the OAuth 2.0 Authorization Code flow. PKCE (code_challenge with method S256) is supported. The only advertised response_type is "code" and response_mode may be query, fragment, or form_post.
      parameters:
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - code
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: scope
        in: query
        required: true
        description: Space-delimited scopes; must include "openid".
        schema:
          type: string
          example: openid profile email
      - name: state
        in: query
        required: false
        schema:
          type: string
      - name: nonce
        in: query
        required: false
        schema:
          type: string
      - name: code_challenge
        in: query
        required: false
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: false
        schema:
          type: string
          enum:
          - S256
      - name: response_mode
        in: query
        required: false
        schema:
          type: string
          enum:
          - query
          - fragment
          - form_post
      responses:
        '302':
          description: Redirect back to redirect_uri with an authorization code (or an error).
          headers:
            Location:
              schema:
                type: string
                format: uri
  /idp/profile/oidc/token:
    post:
      tags:
      - OAuth2
      operationId: token
      summary: Token endpoint
      description: Exchanges an authorization code for tokens or refreshes an access token. Supported grant types are authorization_code and refresh_token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: OAuth 2.0 error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
  /idp/profile/oauth2/introspection:
    post:
      tags:
      - OAuth2
      operationId: introspect
      summary: Token introspection endpoint (RFC 7662)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum:
                  - access_token
                  - refresh_token
      responses:
        '200':
          description: Introspection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
  /idp/profile/oauth2/revocation:
    post:
      tags:
      - OAuth2
      operationId: revoke
      summary: Token revocation endpoint (RFC 7009)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum:
                  - access_token
                  - refresh_token
      responses:
        '200':
          description: Token revoked (or already invalid)
components:
  schemas:
    TokenResponse:
      type: object
      required:
      - access_token
      - token_type
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
        scope:
          type: string
        id_token:
          type: string
          description: Signed JWT ID token (present when openid scope requested).
        refresh_token:
          type: string
    IntrospectionResponse:
      type: object
      properties:
        active:
          type: boolean
        scope:
          type: string
        client_id:
          type: string
        token_type:
          type: string
        exp:
          type: integer
        iat:
          type: integer
        sub:
          type: string
        aud:
          type: string
        iss:
          type: string
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    TokenRequest:
      type: object
      required:
      - grant_type
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
          - refresh_token
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        code_verifier:
          type: string
        refresh_token:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oidc:
      type: openIdConnect
      openIdConnectUrl: https://login.eduid.ch/.well-known/openid-configuration