Sessions
Munchii supports programmatic authentication through GitHub OIDC and AWS IAM, alongside browser sessions and read-only sharing sessions.
GitHub OIDC
/sessions/github/oidcPOSTExchange 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
401The credentials are missing, expired, or invalid.
AWS IAM
/sessions/aws/iamPOSTExchange 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
401The IAM identity could not be mapped to a Munchii principal.403API Gateway rejected the signature or IAM authorization.
Shares
/sessions/sharesPOSTExchange 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
400Use application/json and send valid JSON that matches the expected schema.404The share was not found or has expired.
Browsers
/sessions/github/loginGETRedirect the browser to GitHub to begin signing in.
Sample request
GET /sessions/github/login?redirect=%2F HTTP/1.1 Host: api.munchii.comExample 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=NoneEmpty response body.
Common errors
400The redirect path is invalid.
/sessions/github/callbackGETComplete 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=NoneEmpty response body.
Common errors
400The authorization code or matching OAuth state is missing or invalid.
/sessions/refreshPOSTRenew 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=NoneEmpty response body.
Common errors
401The credentials are missing, expired, or invalid.
/sessions/logoutGETClear 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=NoneEmpty response body.
Common errors
400The redirect path is invalid.