ODC REST API 1: 認証

ODCが提供するREST APIはこれまでユーザー操作系のものだけだったが、運用に使える各種APIが追加された。

これから順番に機能確認していくにあたって、共通で必要となる認証周りについてまとめ、実装例を示す。

なお、折よくPersonal Editionが発表された（無料で使える）。API clientの発行から行えるので、以降の確認にはPEを利用する。

環境情報

ODC Studio (Version 1.6.0)
ODC Personal Edition

PEの概説と取得方法

ODC REST APIとは（2025/09末時点）

ドキュメント

ODC REST APIs

概要

ODCの運用系の機能を操作するREST API群。
ODCのリリース以来、未実装の状態が長かったが、少し前にユーザー・権限操作用APIがリリースされ、2025/9にはDevOps APIもリリースされた。
Announcing OutSystems DevOps APIs

2025/10現在公開されているAPIは以下の通り。

なお、レートリミットが設定されており、この上限を超えるリクエストは行えない。

The rate limit per organization per API domain is as follows:

という記述があることから、Stageを問わず、1契約全体にかかる設定に見える。
Rate limits for the APIs

ODC REST APIの認証

ODC REST APIに対する認証方法は、API authentication and authorizationに記載がある。

OAuth2.0のClient Credentials Grant flowに従ってアクセストークンを取得しておき、後続のAPI呼び出しのリクエストヘッダーAuthorizationに「Bearer アクエストークン」形式でセットする。

API client発行

アクセストークンを取得するにはAPI clientを発行しておく必要がある。
ODC Portalにアクセスし、MANAGE > API clientsページを開く。

ページ右上の「Create API client」ボタンをクリック。
NameとDescriptionは適当に埋める。API clientには有効期限がある。ここではデフォルトの90日を選択しておいた。

その下には、API clientに与える権限を設定するUIがある。
今回は、Portfolio API > /environmentsへのGETで動作確認するので、そのドキュメントから必要な権限を確認してチェックしておく。

The result only shows environments (stages) for which the API Client has Stage > View stage permission.

ということなので、情報を取りたいStageに対する「View Stage」をチェックしておけば良いことがわかる。
ただし、「Stage > View stage」はチェックできないようになっていて、マウスオーバーすると「Inheritable permission」と表示される。つまりStage操作を行う他の権限をつければ付属的にこのチェックも入りそう。

というわけで、User management > View end usersのDevelopment Stageにチェックを入れたところ、以下のようにStage > View stageのDevelopment Stageにもチェックが入った。なお、StageがDevelopmentしかないのはPEであるため。

ここまで入力したら、「Create API client」ボタンをクリック。

Client IDとClient secretが表示されるのでそれぞれ右にあるアイコンをクリックしてクリップボードにコピーし、どこか安全な場所に保存しておく。認証情報なので漏れないように。また、画面を移動してしまうとClient secretは二度と確認できなくなるので注意（わからなくなったら、再度Generateして作り直すことになる）。

実装：Consume REST API

Get access tokenにある手順を実装する。

処理の流れは、

1. OpenID ConfigurationのエンドポイントにGETリクエストして、Tokenエンドポイントを取得する
2. Tokenエンドポイントに、Client IDとClient secretを渡してアクセストークンを取得する
3. アクセストークンをヘッダにセットして実際のAPI呼び出しを行う

1. OpenID ConfigurationエンドポイントからアクセスすべきTokenエンドポイントのURLを取得する

以下のURLの「ODC_PORTAL_DOMAIN」部分を自分のものに置き換える。
ODC Portalにブラウザでアクセスし、ドメイン部分をコピーすると良いだろう。
https://ODC_PORTAL_DOMAIN/identity/.well-known/openid-configuration

実行時にこのURLにアクセスし、TokenエンドポイントのURLを取得する。
アクセストークンを取得する先となるURLなので現実的にはそう簡単には変わらないと思う。しかし、将来の変更に備えて、実行時に毎回OpenID Configurationエンドポイントにアクセスする実装としておいた。

URLがあるのでConsume REST APIのAdd single methodオプションで取り込む。
MethodはデフォルトのGETのままにして、その右のURL欄にURLを貼り付け、Testボタンをクリック。すると、その場でURLにアクセスして、必要なI/F情報を取り込んでくれる。

実行結果が表示されたら、Response test result欄下部に表示される「Copy to response body」ボタンをクリックして、Bodyタブにコピーする（生成されるActionのI/Fに反映するため）。続いて「Finish」ボタンをクリック。

作成されたConsume REST API。このResponse/Token_endpointを後続で使う。

2. Token EndpointにPOSTしてアクセストークンを取得する

こちらもConsume REST APIを作成する。Testタブで以下のように入力し、「Test」ボタンをクリック。実際に使う値で一回テスト実行することで、想定されるレスポンスを使ってActionのI/F定義に使う。

• Method: POSTを選択
• URL: OpenID ConfigurationエンドポイントのURLをブラウザのアドレスバーに直接貼り付け。表示されるJSONから"token_endpoint"項目の値を設定
• Body content > Request欄には、「grant_type=client_credentials&client_id=<clientID>&client_secret=<secret>」を入力<clientId>と<secret>の部分は発行したAPI clientの同項目を設定

Testの結果が帰ってきたら、Response test result欄下部に表示される「Copy to response body」ボタンをクリックして、Bodyタブにコピーする。またこっちのAPIリクエストにはパラメータがあるので、Request test Result欄下部の「Copy to request body」ボタンもクリックしておく。
続いて「Finish」ボタンをクリック。
作成されたConsume REST API。

Input Parameterの設定を調節する。

• grant_type: ドキュメントによると固定値であるため、Default Valueに設定。Send Default ValueプロパティはYesに設定しておく（NoのままだとDefault Valueの時に、項目そのものを省略してしまいエラーになるため）
• client_id, client_secret: 認証情報であり、必須なので、Is Mandatory=Yesに設定

URLを動的にしたい場合の対応

OpenID Configurationが返すTokenエンドポイントへのアクセスにするため、Consume REST APIのURLは実行時に動的に決めたい。
どうすれば良いかというと、

• REST API MethodにInput Parameterを追加してToken_endpointを渡す（ヘッダで渡すなら、Send InをHeaderにしておく）
• REST APIのOnBeforeRequestで渡した値を取り出す
• スキーマ（https://の部分）とホスト名部分を切り出してCustomiedRequest.BaseURLにセット
• ホスト名より後の部分を取り出してCustomizedRequest.URLPathにセット
• いらなくなったTOken_endpointヘッダーは削除

という方法がある。
この変更方法そのものについて以前書いた以下の記事を参照。
https://qiita.com/jyunji_watanabe/items/a6937ed3741910619b6c

追加したパラメータ。

すでにだいぶ長くなってしまったので、この項についてはこの辺にしておく（詳細省略）。

3. アクセストークンを利用してAPIを呼ぶ

取得したアクセストークンを実際に使ってみる。
ここでは扱いが簡単なPortfolio API > /environmentsを使う。

APIページに行くと、OpenAPIの仕様ファイルをダウンロードできる。

このファイルを使って、Consume REST APIのAdd multiple methodsのオプションで取り込む。
Upload fileでファイルを指定して、Add methodsボタンをクリック。

どうせ後でドメイン部分は書き換えるのでどちらでもいい。

今回は使用する/environmentsだけを選択してFinishボタンをクリック。

エラーが出るが、Base URLプロパティを書き換えれば良い。REST APIを選択し、Base URLを書き換える。

書き換える先のBase URLはドキュメントページに戻って、①API SERVER欄下のラジオボタンで下を選択②自分のODC Portalのドメイン部分をコピーして貼り付け③表示されたURLをConsume REST APIのBase URLに貼り付け。

おそらく、本来は、On Before Requestを使ってEntityなどから自動で設定した方がいいと思うが、ここでは動作確認が目的であるため、生成されたREST API Methodにアクセストークンを渡すためのInput Parameterを追加する。追加したInput ParameterのSend InはHeaderにする（これでHTTPリクエストヘッダーに渡される）。また、Name In Requestはドキュメントに従い、Authorizationとする。

実装：Consume REST APIを利用するAction Flow

API ClientのClient IDとClient Secretを保持するためのSettingを作成しておく。少なくともClient SecretのIs secretはYesに設定しておく（パスワードに相当する情報であるため）。テスト前にはODC Portalで値を設定しておく必要がある。

Action Flow例。

PostTokenのToken_endpointには「1.」の呼び出し結果から取得した値を設定している。

またAPIにアクセストークンを渡すときは、「Bearer <アクセストークン>」というフォーマットにする必要がある点に注意。

取得したアクセストークンの扱いについて

アクセストークンには有効期間が12時間あるので、Entityなどに保存しておいて使いまわすことになる。
ここでは、記事が長くなりすぎるので省略する。

なお、アクセストークン・Client secretなどはセキュリティにかなり注意を払う必要があるので、ScreenやBlockのLocal VariableやClientから呼ばれるActionのOutput Parameterに出さないように注意しないといけない。当然Client Variableに保存するのも不可。