> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msu.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MSU OAuth 2.0 Guide

> A complete guide for builder apps to implement the MSU OAuth 2.0 authorization flow — covering token issuance, refresh, introspection, and revocation.

　

This guide explains how builder apps can use the OAuth 2.0 Authorization Code Grant flow to obtain delegated user authorization and access MSU resources via the OpenAPI.

It covers the full token lifecycle: issuance, refresh, introspection, and revocation.

| Item                    | Value                  |
| ----------------------- | ---------------------- |
| **OAuth Server Domain** | `https://oauth.msu.io` |

***

## Overview

<CardGroup cols={2}>
  <Card title="Phase 1. User Authentication & Token Issuance" icon="key">
    Authenticate the user via Authorization Code Grant and issue Access Token and Refresh Token.
  </Card>

  <Card title="Phase 2. Token Refresh" icon="arrows-rotate">
    Use the Refresh Token to renew an expired Access Token.
  </Card>

  <Card title="Phase 3. Token Introspection" icon="shield-check">
    Validate the Access Token and retrieve its metadata.
  </Card>

  <Card title="Phase 4. Token Revocation" icon="ban">
    Revoke the Refresh Token on logout.
  </Card>
</CardGroup>

***

## Sequence Diagram

```mermaid actions={true} theme={null}
sequenceDiagram
  participant Owner as User
  participant Client as Builder App
  participant AS as OAuth Server
  participant RS as MSU Server

  rect rgb(219, 234, 254)
  note over Owner, RS: [Phase 1] User Authentication & Token Issuance
  Owner->>Client: Login request
  Client->>+AS: Authorization Code request (GET /oauth/authorize)
  alt User is not logged in
  AS-->>-Client: Redirect to login page
  Client->>+RS: Login page request
  RS-->>-Owner: Provide login screen
  Owner->>+RS: Login
  RS-->>-Client: Login success response
  Client->>+AS: Re-request Authorization Code (GET /oauth/authorize)
  end
  AS-->>-Client: Deliver Authorization Code (Redirect)
  Client->>+AS: Token issuance request (POST /oauth/token)
  AS-->>-Client: Deliver Access Token & Refresh Token
  end

  rect rgb(254, 243, 199)
  note over Client, AS: [Phase 2] Token Refresh
  Client->>+AS: Token refresh request (POST /oauth/token)
  AS-->>-Client: Issue new Access Token & Refresh Token
  end

  rect rgb(209, 250, 229)
  note over Client, AS: [Phase 3] Token Introspection
  Client->>+AS: Token introspection request (POST /oauth/introspect)
  AS-->>-Client: Return token introspection result
  end

  rect rgb(255, 228, 230)
  note over Client, AS: [Phase 4] Token Revocation
  Client->>+AS: Token revocation request (POST /oauth/revoke)
  AS-->>-Client: Token revocation success response
  end
```

***

## Phase 1 — User Authentication & Token Issuance

<Steps>
  <Step title="User initiates login">
    The user clicks the login button in the builder app.
  </Step>

  <Step title="Authorization Code request">
    The builder app redirects to the OAuth server's authorization endpoint (`/oauth/authorize`) to obtain an Authorization Code. The request includes the app's OAuth Client ID and Redirect URI as query parameters.

    ```json theme={null}
    GET https://oauth.msu.io/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}
    ```

    <Warning>
      The `redirect_uri` must exactly match the URI registered with the OAuth client.
    </Warning>
  </Step>

  <Step title="Redirect to login page">
    The OAuth server detects that the user has no valid session and redirects the browser to the login page.
  </Step>

  <Step title="Login page request">
    The user's browser requests the login page from the MSU server following the redirect.
  </Step>

  <Step title="Login screen provided">
    The MSU server serves a wallet address-based login form to the user's browser.
  </Step>

  <Step title="User logs in">
    The user submits a login request to the MSU server using their wallet address.
  </Step>

  <Step title="Login success response">
    The MSU server processes the login and returns a success response.
  </Step>

  <Step title="Re-request Authorization Code">
    After login is complete, the builder app re-requests an Authorization Code from the OAuth server.

    ```json theme={null}
    GET https://oauth.msu.io/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}
    ```
  </Step>

  <Step title="Authorization Code delivered">
    The OAuth server redirects to the `redirect_uri` provided in the request, delivering the Authorization Code.

    ```json theme={null}
    {REDIRECT_URI}?code={AUTHORIZATION_CODE}
    ```
  </Step>

  <Step title="Token issuance request">
    The builder app sends the Authorization Code to the OAuth token endpoint (`/oauth/token`) with client credentials via HTTP Basic Auth.

    ```json theme={null}
    POST https://oauth.msu.io/oauth/token
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

    grant_type=authorization_code&code={AUTHORIZATION_CODE}&redirect_uri={REDIRECT_URI}
    ```
  </Step>

  <Step title="Access Token & Refresh Token delivered">
    The OAuth server validates the Authorization Code and client credentials, then issues and returns the tokens.

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im1zdS1vYXV0aCIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 600,
      "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im1zdS1vYXV0aCIsInR5cCI6IkpXVCJ9...",
      "scope": "enhancement"
    }
    ```
  </Step>
</Steps>

***

## Phase 2 — Token Refresh

<Steps>
  <Step title="Token refresh request">
    When the Access Token expires, use the Refresh Token to request a new one from the OAuth token endpoint (`/oauth/token`).

    ```json theme={null}
    POST https://oauth.msu.io/oauth/token
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

    grant_type=refresh_token&refresh_token={REFRESH_TOKEN}
    ```
  </Step>

  <Step title="New Access Token & Refresh Token issued">
    The OAuth server validates the Refresh Token and issues a new Access Token and Refresh Token.

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im1zdS1vYXV0aCIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 600,
      "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im1zdS1vYXV0aCIsInR5cCI6IkpXVCJ9...",
      "scope": "enhancement"
    }
    ```
  </Step>
</Steps>

***

## Phase 3 — Token Introspection

<Steps>
  <Step title="Token introspection request">
    To verify whether an Access Token is valid, send a request to the OAuth Introspect endpoint (`/oauth/introspect`).

    ```json theme={null}
    POST https://oauth.msu.io/oauth/introspect
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

    token={ACCESS_TOKEN}&token_type_hint=access_token
    ```
  </Step>

  <Step title="Introspection result returned">
    The OAuth server returns the validation result along with token metadata such as issuer, expiration, and subject.

    ```json theme={null}
    {
      "active": true,
      "client_id": "e5451c6e-7bc1-4ec3-bd9c-98c18a7d3290",
      "exp": 1781673359,
      "iat": 1781672759,
      "iss": "NEXPACE",
      "jti": "b8ddec65-3697-441c-a118-fa31a08ccb42",
      "scope": "enhancement",
      "sub": "0x1234567890AbcdEF1234567890aBcdef12345678",
      "token_type": "Bearer"
    }
    ```
  </Step>
</Steps>

***

## Phase 4 — Token Revocation

<Steps>
  <Step title="Token revocation request">
    To invalidate a Refresh Token, send a request to the OAuth Revoke endpoint (`/oauth/revoke`).

    ```json theme={null}
    POST https://oauth.msu.io/oauth/revoke
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

    token={REFRESH_TOKEN}&token_type_hint=refresh_token
    ```
  </Step>

  <Step title="Revocation success response">
    The OAuth server invalidates the token and returns a success response (`200 OK`).
  </Step>
</Steps>

***

For detailed API specifications of each endpoint, refer to the individual pages under the **OAuth** section.

　

***