NYCU OAuth API

openapi: 3.0.3
info:
  title: NYCU OAuth API
  description: >-
    The National Yang Ming Chiao Tung University (NYCU) OAuth service — the university's own
    OAuth 2.0 (RFC 6749) authorization server, operated by the NYCU Information Technology
    Service Center (資訊技術服務中心) at https://id.nycu.edu.tw. It lets on-campus and approved
    third-party applications authenticate NYCU users against the university single sign-on
    account and retrieve consented identity attributes. Only the Authorization Code grant is
    offered. Applications register a client and a redirect-URI whitelist before use; the
    `profile` scope is open to any registered developer, while the `name` and `status` scopes
    carry sensitive personal data and require review and approval by the Information Technology
    Service Center.

    This document was DERIVED by API Evangelist from the university's own published developer
    documentation at https://id.nycu.edu.tw/docs/ and its terms of service at
    https://id.nycu.edu.tw/policy/. NYCU does not publish a machine-readable description of this
    service; no OpenID Connect discovery document is served (both
    /.well-known/openid-configuration and /.well-known/oauth-authorization-server return 404).
    Endpoint paths, parameters, scopes and response shapes are transcribed from that
    documentation and were probed for existence — they were not inferred from a vendor template.
  version: '2025-10-28'
  contact:
    name: NYCU OAuth administrators, Information Technology Service Center
    email: oibi@nycu.edu.tw
    url: https://id.nycu.edu.tw/docs/
  termsOfService: https://id.nycu.edu.tw/policy/
  x-operator: institution
  x-operator-evidence: >-
    id.nycu.edu.tw resolves to 140.113.199.41, inside NYCU's own 140.113.0.0/16 allocation; the
    service, its documentation, its terms of service and its issue tracker
    (github.com/NYCU-OAuth) are all published by the university itself.
  x-provenance:
    method: derived
    source: https://id.nycu.edu.tw/docs/
    generated: '2026-09-01'
servers:
  - url: https://id.nycu.edu.tw
    description: NYCU OAuth production authorization server.
tags:
  - name: OAuth
    description: OAuth 2.0 authorization-code endpoints.
  - name: Profile
    description: Consented NYCU user identity attributes.
paths:
  /o/authorize/:
    get:
      tags: [OAuth]
      operationId: authorize
      summary: Begin the authorization-code flow
      description: >-
        Redirects the end user to the NYCU single sign-on login and consent screen. On approval
        the browser is redirected back to the registered redirect URI with `code` and `state`
        query parameters.
      parameters:
        - name: response_type
          in: query
          required: true
          description: Must be `code`; the authorization-code grant is the only grant offered.
          schema:
            type: string
            enum: [code]
        - name: client_id
          in: query
          required: true
          description: Client ID issued when the application was registered at /apply/app.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: >-
            Redirect URI to return the user to. Must exactly match one of the URIs whitelisted
            on the registered client.
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: true
          description: >-
            Space-separated scopes. `profile` is open to any registered developer; `name` and
            `status` are sensitive and require prior approval.
          schema:
            type: string
            example: profile name
        - name: state
          in: query
          required: false
          description: Opaque random string echoed back on redirect; used for CSRF protection.
          schema:
            type: string
      responses:
        '302':
          description: >-
            Redirect to the NYCU login/consent screen, and afterwards to the registered
            redirect URI carrying `code` and `state`.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '400':
          description: Invalid client, redirect URI or scope.
  /o/token/:
    post:
      tags: [OAuth]
      operationId: token
      summary: Exchange an authorization code for an access token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                access_token: ACCESS_TOKEN
                expires_in: 36000
                token_type: Bearer
                scope: profile email
                refresh_token: REFRESH_TOKEN
        '400':
          description: Invalid grant, code, redirect URI or client credentials.
  /o/revoke_token/:
    post:
      tags: [OAuth]
      operationId: revokeToken
      summary: Revoke an access or refresh token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
      responses:
        '200':
          description: Token revoked. The response body is empty.
        '400':
          description: Invalid token or client credentials.
  /api/profile/:
    get:
      tags: [Profile]
      operationId: getProfile
      summary: Get the consented user's account name and email
      description: >-
        Non-sensitive. Requires the `profile` scope, which any registered application may
        request.
      security:
        - oauth2: [profile]
      responses:
        '200':
          description: The consented user's basic identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
              example:
                username: testuser
                email: test@nycu.edu.tw
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: The token does not carry the `profile` scope.
  /api/name/:
    get:
      tags: [Profile]
      operationId: getName
      summary: Get the consented user's personal name
      description: >-
        Sensitive (機敏). Requires the `name` scope, which must be requested through the
        application management console and approved by the Information Technology Service
        Center. In principle only systems developed or operated by the university are granted
        it.
      security:
        - oauth2: [name]
      responses:
        '200':
          description: The consented user's name and account name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Name'
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: The token does not carry the approved `name` scope.
  /api/status/:
    get:
      tags: [Profile]
      operationId: getStatus
      summary: Get the consented user's enrollment or employment status
      description: >-
        Sensitive (機敏). Requires the `status` scope, subject to the same review and approval
        as `name`.
      security:
        - oauth2: [status]
      responses:
        '200':
          description: The consented user's student/staff status and account name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: The token does not carry the approved `status` scope.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        NYCU OAuth 2.0 (RFC 6749) authorization code grant. Clients register at
        https://id.nycu.edu.tw/apply/app. The terms of service require HTTPS, PKCE and CSRF
        protection in client implementations.
      flows:
        authorizationCode:
          authorizationUrl: https://id.nycu.edu.tw/o/authorize/
          tokenUrl: https://id.nycu.edu.tw/o/token/
          refreshUrl: https://id.nycu.edu.tw/o/token/
          scopes:
            profile: Account name and NYCU email address. Non-sensitive; open to registered developers.
            name: The user's personal name. Sensitive; requires approval.
            status: The user's enrollment or employment status. Sensitive; requires approval.
  schemas:
    TokenRequest:
      type: object
      required: [grant_type, code, redirect_uri, client_id, client_secret]
      properties:
        grant_type:
          type: string
          enum: [authorization_code, refresh_token]
          description: >-
            `authorization_code` to exchange a fresh code; `refresh_token` to renew, which the
            terms of service list as a supported flow.
        code:
          type: string
          description: The authorization code returned to the redirect URI.
        redirect_uri:
          type: string
          format: uri
          description: The same redirect URI used in the authorization request.
        client_id:
          type: string
        client_secret:
          type: string
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: integer
          description: Access-token lifetime in seconds (36000 in the documented example).
        token_type:
          type: string
          enum: [Bearer]
        scope:
          type: string
          description: Space-separated scopes actually granted.
        refresh_token:
          type: string
    RevokeRequest:
      type: object
      required: [token, client_id]
      properties:
        token:
          type: string
          description: The access token or refresh token to revoke.
        client_id:
          type: string
        client_secret:
          type: string
          description: Required for confidential clients.
    Profile:
      type: object
      properties:
        username:
          type: string
          description: NYCU single sign-on account name (student or staff ID).
        email:
          type: string
          format: email
          description: NYCU email address.
    Name:
      type: object
      properties:
        username:
          type: string
        name:
          type: string
          description: The user's personal name.
    Status:
      type: object
      properties:
        username:
          type: string
        status:
          type: string
          description: Enrollment (在學) or employment (在職) status.