Sessions

Munchii supports programmatic authentication through GitHub OIDC and AWS IAM, alongside browser sessions and read-only sharing sessions.

GitHub OIDC

/sessions/github/oidc
  • POSTExchange a GitHub Actions OIDC token for a Munchii access token.

    Sample request

    POST /sessions/github/oidc HTTP/1.1
    Host: api.munchii.com
    Authorization: Bearer <github-oidc-token>

    Example response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "value": "<access-token>"
    }

    Common errors

    • 401 The credentials are missing, expired, or invalid.

AWS IAM

/sessions/aws/iam
  • POSTExchange an AWS IAM-authenticated request for a Munchii access token.

    Sample request

    POST /sessions/aws/iam HTTP/1.1
    Host: api.munchii.com
    X-Amz-Date: <signing-timestamp>
    Authorization: AWS4-HMAC-SHA256 Credential=<credential>, SignedHeaders=<headers>, Signature=<signature>

    Example response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "value": "<access-token>"
    }

    Common errors

    • 401 The IAM identity could not be mapped to a Munchii principal.
    • 403 API Gateway rejected the signature or IAM authorization.

Shares

/sessions/shares
  • POSTExchange a share link token for a read-only pipeline session.

    Sample request

    POST /sessions/shares HTTP/1.1
    Host: api.munchii.com
    Content-Type: application/json
    
    {
      "shareId": "share_123"
    }

    Example response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "data": {
        "value": "<share-access-token>",
        "target": {
          "kind": "pipeline",
          "id": "pipeline_123",
          "name": "web"
        },
        "parent": {
          "kind": "space",
          "id": "space_123",
          "name": "engineering"
        }
      }
    }

    Common errors

    • 400 Use application/json and send valid JSON that matches the expected schema.
    • 404 The share was not found or has expired.

Browsers

/sessions/github/login
  • GETRedirect the browser to GitHub to begin signing in.

    Sample request

    GET /sessions/github/login?redirect=%2F HTTP/1.1
    Host: api.munchii.com

    Example response

    HTTP/1.1 302 Found
    Location: https://github.com/login/oauth/authorize?client_id=<client-id>&state=<state>
    Set-Cookie: __Host-munchii_oauth_state=<nonce>; Path=/; HttpOnly; Secure; SameSite=None

    Empty response body.

    Common errors

    • 400 The redirect path is invalid.
/sessions/github/callback
  • GETComplete the GitHub sign-in flow and establish a browser session.

    Sample request

    GET /sessions/github/callback?code=<authorization-code>&state=<state> HTTP/1.1
    Host: api.munchii.com
    Cookie: __Host-munchii_oauth_state=<nonce>

    Example response

    HTTP/1.1 302 Found
    Location: /
    Set-Cookie: __Host-munchii_access_token=<access-token>; Path=/; HttpOnly; Secure; SameSite=None
    Set-Cookie: __Host-munchii_session=<refresh-token>; Path=/; HttpOnly; Secure; SameSite=None

    Empty response body.

    Common errors

    • 400 The authorization code or matching OAuth state is missing or invalid.
/sessions/refresh
  • POSTRenew the browser session using its refresh token.

    Sample request

    POST /sessions/refresh HTTP/1.1
    Host: api.munchii.com
    Cookie: __Host-munchii_session=<refresh-token>

    Example response

    HTTP/1.1 204 No Content
    Set-Cookie: __Host-munchii_access_token=<access-token>; Path=/; HttpOnly; Secure; SameSite=None
    Set-Cookie: __Host-munchii_session=<refresh-token>; Path=/; HttpOnly; Secure; SameSite=None

    Empty response body.

    Common errors

    • 401 The credentials are missing, expired, or invalid.
/sessions/logout
  • GETClear the browser’s session cookies and redirect.

    Sample request

    GET /sessions/logout?redirect=%2F HTTP/1.1
    Host: api.munchii.com
    Cookie: __Host-munchii_session=<refresh-token>

    Example response

    HTTP/1.1 302 Found
    Location: /
    Set-Cookie: __Host-munchii_access_token=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=None
    Set-Cookie: __Host-munchii_session=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=None

    Empty response body.

    Common errors

    • 400 The redirect path is invalid.