API リファレンス | 4S Developer

はじめに

「4S でログイン」は、OAuth 2.0 / OpenID Connect (OIDC) 準拠の認証機能です。外部アプリケーションは 4S アカウントを使ったログインと、ユーザーに代わって 4S の読み取り（GET）API を利用できます。

標準準拠のため、NextAuth (Auth.js)、openid-client など一般的な OIDC ライブラリがそのまま利用できます。対応フローは Authorization Code + PKCE (S256) のみです。

アプリの登録は 4S の開発者メニュー（https://4s.link/developer）から行います。登録すると client_id と client_secret が発行されます。client_secret は登録直後に一度だけ表示されるため、安全な場所に保管してください。

基本情報

項目	値
Issuer	https://api.4s.link
対応フロー	Authorization Code + PKCE (S256)
クライアント認証	client_secret_basic / client_secret_post / none (public + PKCE)
ID Token 署名	RS256
アクセストークン有効期限	1 時間
リフレッシュトークン有効期限	60 日（ローテーション方式）

エンドポイント
# OIDC Discovery
https://api.4s.link/.well-known/openid-configuration

# JWKS (公開鍵)
https://api.4s.link/.well-known/jwks.json

# 認可エンドポイント
https://4s.link/oauth/authorize

# トークンエンドポイント
https://api.4s.link/oauth/token

# UserInfo
https://api.4s.link/oauth/userinfo

# トークン失効
https://api.4s.link/oauth/revoke

認証フロー

Authorization Code + PKCE フローの流れは次のとおりです。(1) アプリが code_verifier を生成し、その S256 ハッシュ（code_challenge）を付けて認可エンドポイントへユーザーをリダイレクトする。(2) ユーザーが 4S にログインして同意すると、redirect_uri に認可コード（code）が返る。(3) アプリはトークンエンドポイントで code + code_verifier をトークンに交換する。

GEThttps://4s.link/oauth/authorize

認可エンドポイントはブラウザでユーザーをリダイレクトさせる URL です（API ではありません）。以下のクエリパラメータを付与してください。

クエリパラメータ

response_typestring必須

code 固定

client_idstring必須

開発者メニューで発行されたクライアント ID

redirect_uristring必須

登録済みのリダイレクト URI と完全一致すること

statestring

CSRF 対策のランダム値。コールバックでそのまま返される（強く推奨）

noncestring

ID Token の nonce クレームとして返されるランダム値（推奨）

code_challengestring必須

code_verifier の SHA-256 を base64url エンコードした値

code_challenge_methodstring必須

S256 固定

promptstring

consent を指定すると同意済みでも同意画面を再表示する。none はサポートされず interaction_required が返る

ユーザーが承認すると redirect_uri に ?code=...&state=... が付与されて戻ります。拒否した場合や検証エラーの場合は ?error=access_denied などが返ります。認可コードの有効期限は 5 分間・1 回限りです。

認可リクエストの例
const crypto = require("crypto");

const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

console.log({ codeVerifier, codeChallenge });

Discovery / JWKS

GET/.well-known/openid-configuration

OIDC Discovery ドキュメントです。エンドポイント URL・署名アルゴリズムなどのメタデータを返します。OIDC ライブラリには issuer としてこのオリジンを設定すれば、残りは自動で解決されます。

GET/.well-known/jwks.json

ID Token の署名を検証するための公開鍵（JWK Set）です。ID Token のヘッダの kid と一致する鍵で RS256 署名を検証してください。鍵はローテーションされることがあるため、JWKS は都度取得するかキャッシュの失効を実装してください（Cache-Control: max-age=300）。

curl https://api.4s.link/.well-known/openid-configuration

トークンエンドポイント

POST/oauth/token

認可コードをトークンに交換する、またはリフレッシュトークンでトークンを更新するエンドポイントです。リクエストボディは application/x-www-form-urlencoded で送信してください。confidential クライアントは client_secret_basic（Authorization: Basic）または client_secret_post（ボディ）で認証します。

grant_type=authorization_code のパラメータ

grant_typestring必須

authorization_code

codestring必須

コールバックで受け取った認可コード

redirect_uristring必須

認可リクエスト時と同じ値

code_verifierstring必須

code_challenge の元になった PKCE 検証値

grant_type=refresh_token のパラメータ

grant_typestring必須

refresh_token

refresh_tokenstring必須

有効なリフレッシュトークン

リフレッシュトークンはローテーション方式です。refresh_token グラントを実行するたびに新しいリフレッシュトークンが発行され、古いトークンは無効になります。失効済みリフレッシュトークンの再利用を検知した場合、安全のためそのユーザー×クライアントのすべてのトークンが失効します。必ず最新のリフレッシュトークンを保存してください。

コード交換
curl -X POST https://api.4s.link/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://example.com/callback" \
  -d "code_verifier=CODE_VERIFIER"

ID Token

トークンレスポンスには常に ID Token（RS256 署名の JWT）が含まれます。検証時は (1) JWKS の kid 一致鍵で署名を検証、(2) iss が issuer と一致、(3) aud が自分の client_id と一致、(4) exp が未来、(5) 認可リクエストで nonce を送った場合は nonce クレームの一致、を確認してください。OIDC ライブラリを使えばこれらは自動で行われます。

主なクレーム

クレーム	説明
`sub`	ユーザーの一意 ID（4S のユーザー ID）
`iss`	発行者（issuer）
`aud`	クライアント ID
`auth_time`	ユーザーが認可した時刻（Unix 秒）
`nonce`	認可リクエストの nonce（送信した場合のみ）
`name / given_name / family_name / picture / profile / preferred_username / locale`	プロフィール情報（常に含まれる）
`email / email_verified`	メールアドレス（常に含まれる）

ID Token ペイロードの例
{
  "sub": "a1b2c3d4-....",
  "iss": "https://api.4s.link",
  "aud": "YOUR_CLIENT_ID",
  "iat": 1783900000,
  "exp": 1783903600,
  "auth_time": 1783899990,
  "nonce": "RANDOM_NONCE",
  "name": "太郎 山田",
  "given_name": "太郎",
  "family_name": "山田",
  "picture": "https://.../avatar.png",
  "profile": "https://4s.link/taro",
  "preferred_username": "taro",
  "locale": "ja",
  "email": "taro@example.com",
  "email_verified": true
}

トークン失効

POST/oauth/revoke

RFC 7009 準拠のトークン失効エンドポイントです。ユーザーがアプリからログアウトした際などに、不要になったトークンを失効させてください。リフレッシュトークンを失効させると、そこから発行されたアクセストークンも同時に失効します。RFC 7009 の仕様どおり、不明なトークンを指定しても 200 が返ります。

ボディパラメータ

tokenstring必須

失効させるアクセストークンまたはリフレッシュトークン

トークンの失効
curl -X POST https://api.4s.link/oauth/revoke \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=4s_rt_..."

API を呼び出す

取得したアクセストークンを Authorization: Bearer ヘッダに付けて、4S の API を呼び出します。OAuth アクセストークンで利用できるのは、以下の各カテゴリに記載された読み取り・更新エンドポイント（許可リスト）に限られます。許可リストに無いメソッドとパスの組み合わせはすべて 403 になります。

共通仕様

項目	内容
ベース URL	https://api.4s.link
認証	Authorization: Bearer <access_token>
利用可能な範囲	各カテゴリに記載されたメソッド + パスの組み合わせのみ（GET / POST / PUT / PATCH / DELETE）
ページネーション	一覧系は page / perPage クエリ。レスポンスに pageInfo（totalCount / totalPages / page / perPage）
レート制限	アプリ × ユーザーごとに既定 60 req/分・1,000 req/時。全レスポンスに X-RateLimit-* ヘッダが付く（「レート制限」を参照）
エラー（401）	トークンが無効・失効・期限切れ
エラー（403）	許可リストに無いメソッド + パスへのアクセス（/admin 配下は常に不可）
権限	各エンドポイントの権限検査は通常のログイン時と同じ。イベントスタッフのロールや組織・コミュニティの管理者権限が必要な操作は、認可したユーザー自身がその権限を持っている必要がある
メールアドレス	/manage 配下のレスポンスからは email フィールドが再帰的に除去される（アンケートの自由記述回答は対象外）

利用できるエンドポイントの全一覧を以下のカテゴリに掲載しています。パス末尾のスラッシュは無視され、/api・/v1 プレフィックスを付けても同じエンドポイントに届きます。パスの大文字小文字は区別され、HEAD メソッドには対応していません。

curl https://api.4s.link/users/me \
  -H "Authorization: Bearer 4s_at_..."

レート制限

アクセストークンでの API 呼び出しには、アプリと利用ユーザーの組み合わせ（アプリ × ユーザー）ごとにレート制限が掛かります。制限はアプリ全体ではなくユーザーごとに数えるため、あるユーザーが上限に達しても他のユーザーへの API 呼び出しには影響しません。

上限

ウィンドウ	既定の上限	説明
1 分	60	短時間のバーストを抑えるための上限
1 時間	1,000	総量の上限。分ウィンドウの境界をまたぐ連続アクセスもこの上限で抑えられる

上限はアプリごとに個別設定できます。既定値では足りない用途がある場合は 4S の運営までお問い合わせください。現在アプリに適用されている上限は、開発者メニューのアプリ詳細ページ、または下記のレスポンスヘッダで確認できます。

レスポンスヘッダ

ヘッダ	内容
`X-RateLimit-Limit-Minute`	1 分あたりの上限
`X-RateLimit-Remaining-Minute`	1 分あたりの残り回数
`X-RateLimit-Limit-Hour`	1 時間あたりの上限
`X-RateLimit-Remaining-Hour`	1 時間あたりの残り回数
`X-RateLimit-Reset`	残りが少ない方のウィンドウがリセットされる時刻（UNIX 秒）
`Retry-After`	429 のときのみ返る。再試行までに待つべき秒数

これらのヘッダは 429 のときだけでなく、すべての成功レスポンスにも付きます。残り回数を見てリクエストの間隔を調整すれば、429 に当たらずに運用できます。ブラウザから実行する場合も CORS で公開されているため読み取れます。

上限を超えると 429 Too Many Requests が返ります。レスポンスボディは { "error": "...", "errorCode": 60007 } です。上限を超えている間のリクエストもカウントされるため、429 が返ったら Retry-After の秒数だけ待ってから再試行してください。即座にリトライを繰り返すと解放が遅くなります。

レート制限はアクセストークンでの API 呼び出しにのみ適用されます。Discovery・JWKS・トークンエンドポイント（/oauth/token）・失効エンドポイント（/oauth/revoke）は対象外です。

レスポンスヘッダの確認
curl -i https://api.4s.link/users/me \
  -H "Authorization: Bearer 4s_at_..."

# HTTP/1.1 200 OK
# X-RateLimit-Limit-Minute: 60
# X-RateLimit-Remaining-Minute: 43
# X-RateLimit-Limit-Hour: 1000
# X-RateLimit-Remaining-Hour: 912
# X-RateLimit-Reset: 1755500460

429 のレスポンス
{
  "error": "Too many requests. Please slow down.",
  "errorCode": 60007
}

エラーリファレンス

トークンエンドポイント・UserInfo・イベント API は RFC 6749 / RFC 6750 形式のエラー（{ error, error_description }）を返します。認可エンドポイントのエラーは redirect_uri へのクエリパラメータで返ります（redirect_uri 自体が不正な場合を除く）。

エラー	発生箇所	説明
`invalid_client`	token / revoke	クライアント認証の失敗、またはアプリがサスペンド中
`invalid_grant`	token	認可コード / リフレッシュトークンが無効・期限切れ・使用済み、PKCE 検証失敗、redirect_uri 不一致、連携解除済み
`invalid_request`	token / authorize	必須パラメータの不足・不正
`access_denied`	authorize	ユーザーが認可を拒否した
`interaction_required`	authorize	prompt=none が指定されたが対話が必要（サイレント認証は非対応）
`unsupported_grant_type`	token	authorization_code / refresh_token 以外の grant_type
`401 Unauthorized`	リソース API	アクセストークンが無効・失効・期限切れ、またはアプリがサスペンド中
`403 Forbidden`	リソース API	許可された GET エンドポイント以外へのアクセス（各カテゴリに記載のエンドポイントのみ利用可）
`429 Too Many Requests`	リソース API	レート制限の超過（errorCode: 60007）。Retry-After の秒数だけ待ってから再試行する（「レート制限」を参照）

エラーレスポンスの例
{
  "error": "invalid_grant",
  "error_description": "PKCE verification failed"
}

連携例

汎用 OIDC ライブラリでは issuer を設定するだけで Discovery から各エンドポイントが自動解決されます。NextAuth (Auth.js) v5 の設定例を右に示します。redirect_uri（例: https://your-app.com/api/auth/callback/4s）を開発者メニューで忘れずに登録してください。

既知の制限: prompt=none（サイレント認証）と Dynamic Client Registration には対応していません。ID Token に at_hash クレームは含まれません。

NextAuth (Auth.js) v5
import NextAuth from "next-auth";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: "4s",
      name: "4S",
      type: "oidc",
      issuer: "https://api.4s.link",
      clientId: process.env.FOURS_CLIENT_ID,
      clientSecret: process.env.FOURS_CLIENT_SECRET,
      authorization: {
        params: { scope: "openid profile email" },
      },
      // PKCE と state は NextAuth がデフォルトで有効化します
    },
  ],
});

デモアプリ

Next.js + TypeScript で実装した「4S でログイン」の動作サンプルです。ログインフロー（Authorization Code + PKCE）とプロフィール取得の実装を確認できます。