National Yang Ming Chiao Tung University Profile API

openapi: 3.2.0
info:
  title: NYCU OAuth Profile 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.
  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: Profile
  description: Consented NYCU user identity attributes.
paths:
  /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:
  schemas:
    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.
    Status:
      type: object
      properties:
        username:
          type: string
        status:
          type: string
          description: Enrollment (在學) or employment (在職) status.
    Name:
      type: object
      properties:
        username:
          type: string
        name:
          type: string
          description: The user's personal name.
  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.