API 認証

すべての API 要求は、権限付与ヘッダーを介して認証される必要があります。Infobip API には、次の認証方法が用意されています。

HTTP 基本認証
API キー
IBSSOトークン
OAuth 2.0 (英語)

現在の技術スタックとセキュリティ要件レベルに合わせて、好みの方法を選択してください。これらの方法の多くは中間者攻撃に対して脆弱であるため、暗号化された接続やSSLなどの他のセキュリティメカニズムと組み合わせることをお勧めします。

エラーセクションを参照して潜在的な問題のトラブルシューティングを行うか、Infobip サポートチームにお問い合わせください。

基本的な

基本認証 は、すべての API 要求でユーザー名とパスワードを送信することで機能します。通常、この方法は、APIキーが使用できない状況で使用されます。たとえば、API キーを生成する API メソッドは、Basic で認証できます。

基本認証は、暗号化された資格情報を元の値に戻すのが簡単なため、最も推奨されない方法です。HTTP 認証リソース (opens in a new tab)を参照して、Basic認証でサーバーへのアクセスを制限する方法を確認してください。

この方法に関するいくつかの重要な事実を次に示します。

HTTPプロトコル自体に組み込まれている
資格情報は、Base64 形式 (たとえば、RFC2045-MIME (opens in a new tab) バリアントを使用) でエンコードし、コロン (:)
エンコードされた資格情報は、ヘッダーの Basic の後に追加されます

例 - HTTP クライアント

Infobip API クライアントライブラリ (opens in a new tab) を使用する場合、資格情報を手動でエンコードする必要はありません。ユーザー名とパスワードを指定する必要があるのは、クライアントオブジェクトのインスタンスを作成するときだけです。

REQUEST SAMPLES


    curl -L -g -X GET 'https://{baseUrl}/sms/2/text/advanced' /
    -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='

 
    String auth = username + ":" + password;
    String encoded = Base64.getEncoder().encodeToString(auth.getBytes("UTF-8"));
     
    String messageText = "This is test message sent using OkHttpClient and Basic auth";
    String jsonBody = String.format(
            "{\"messages\":[{\"from\":\"%s\",\"destinations\":[{\"to\":\"%s\"}],\"text\":\"%s\"}]}",
            SENDER, PHONE_NUMBER, messageText);
     
    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
     
    Request request = new Request.Builder()
            .url(BASE_URL + "/sms/2/text/advanced")
            .addHeader("Authorization", "Basic " + encoded)
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .post(requestBody)
            .build();
     
    OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
    Response response = httpClient.newCall(request).execute();
    System.out.println(response.body().string());

 
    string username = "USERNAME";
    string password = "PASSWORD";
    string concatenated = $"{username}:{password}";
    string encoded = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(concatenated));
     
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", encoded);
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

例 - API クライアントライブラリ

Infobip API クライアントライブラリ (opens in a new tab) を使用する場合、上記のように資格情報データを手動でエンコードする必要はありません。ユーザー名とパスワードを指定する必要があるのは、次の例に示すように、クライアントオブジェクトのインスタンスを作成するときだけです。

csharp

 
    var configuration = new Configuration()
    {
        BasePath = "BASE_URL",
        Username = "USERNAME",
        Password = "PASSWORD"
    };

基本認証の API スコープ

基本認証に関連付けられた API スコープについては、専用の [ユーザーロールと API スコープ](/essentials/api-essentials/api-authorization#ユーザーロールと api-scopes-api-scopes) セクションを参照してください。

APIキーヘッダー

APIキーは、クライアントが API 呼び出しを行うときに提供するアクセストークンです。これは、アクセスをセキュリティで保護する簡単な方法であるため、REST API で使用される最も一般的な認証方法です。キーは、クエリ文字列または要求ヘッダーとして送信できます。アカウントを作成すると、自動的にAPIキーが割り当てられます。Infobip APIキー管理 (opens in a new tab) ページを使用して、より多くのキーを生成し、既存のキーを管理します。

この方法に関するいくつかの重要な事実を次に示します。

API キーは、専用の API メソッドを呼び出すことで生成できます
キーはいつでも取り消すことができるため、複数のアプリケーションまたはユースケース間で API アクセス権を分離する場合に便利です
Infobip API キーには、最終的に無効になる有効期限が事前定義されています

例 - HTTP クライアント

以下の例は、クライアントライブラリ (opens in a new tab)を使用する場合にAPIキー認証を指定する方法を示しています。

REQUEST SAMPLES


    curl -L -g -X GET 'https://{baseUrl}/sms/2/text/advanced' /
    -H 'Authorization: App 003026abc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9'

 
    Request request = new Request.Builder()
            .url("BASE_URL" + "/sms/2/text/advanced")
            .addHeader("Authorization", "App " + apiKey)
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .post(requestBody)
            .build();

 
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
     
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("App", "API_KEY");
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

例 - API クライアントライブラリ

以下の例は、API キー認証を使用して HTTP 要求を準備する方法を示しています。この要求は、基本認証要求を使用するよりもはるかに簡単であることに注意してください。

REQUEST SAMPLES

 
    ApiClient apiClient = ApiClient.forApiKey(ApiKey.from(API_KEY))
        .withBaseUrl(BaseUrl.from(BASE_URL))
        .build();

 
    var configuration = new Configuration()
    {
        BasePath = "BASE_URL",
        ApiKeyPrefix = "App",
        ApiKey = "API_KEY"
    };

API キーの API スコープ

API スコープの詳細については、専用の API スコープセクションを参照してください。

IBSSO トークンヘッダー

IBSSOトークンはセッションベースであり、トークンは短期間有効です。これにより、最終的にはこの方法の安全性が高まりますが、認証を有効に保つためにより多くのメンテナンスが必要になります。

通常、この種類の認証は、システム全体で複数のサインインを回避するシングルサインオンシナリオで使用されます。また、機密データをさまざまなエンタープライズシステムに分散させることなく、一元的に処理する必要があるシナリオでも役立つ場合があります。

この方法に関するいくつかの重要な事実を次に示します。

すべての API 要求は、セッショントークン (opens in a new tab)で認証されます
既定では、IBSSO トークンは 60 分後に期限切れになり、その後、新しいトークンを作成する必要があります
新しいトークンを作成したいが、前のトークンの有効期限がまだ切れていない場合は、最初にセッションを破棄 (opens in a new tab)する必要があります
専用の API 呼び出し (opens in a new tab)でセッションの長さを短縮できます

IBSSOトークンの使用方法

呼び出しを行ってセッションエンドポイントを作成し、応答からトークンを取得します。
後続のすべての呼び出しの権限付与ヘッダーに IBSSO とトークンを含めます: 権限付与: IBSSO 2f9b4d31-2d0d-49a8-85f0-9b862bdca394
必要に応じて、セッションを破棄して、セッションの長さを必要に応じて調整します。既定では、セッションは 60 分後に期限切れになります。

HTTP 要求

IBSSOトークンの取得

Create session エンドポイントを呼び出して、セッションを作成します。応答には、 Send SMS (opens in a new tab) などの他の API エンドポイントへの要求の HTTP ヘッダーで使用できるトークンが含まれます。

REQUEST SAMPLES

 
    private static class IbssoResponse {
        public IbssoResponse() {
            super();
        }
     
        @JsonProperty("token")
        public String token;
     
        @JsonGetter("token")
        public String getToken() {
            return token;
        }
     
        @JsonSetter("token")
        public void setToken(String token) {
            this.token = token;
        }
    }
     
    String jsonBody = String.format("{\"username\":\"%s\",\"password\":\"%s\"}", "USERNAME", "PASSWORD");
     
    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
     
    Request request = new Request.Builder()
            .url("BASE_URL" + "/auth/1/session")
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .post(requestBody)
            .build();
     
    OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
    Response response = httpClient.newCall(request).execute();
    String responseBody = response.body().string();
    System.out.println(responseBody);
     
    IbssoResponse ibssoResponse = new ObjectMapper().readValue(responseBody, IbssoResponse.class);
     
    return ibssoResponse.token;

 
    public class IbssoResponse
    {
        [System.Text.Json.Serialization.JsonPropertyName("token")]
        public string Token { get; set; }
    }
     
    string username = "USERNAME";
    string password = "PASSWORD";
     
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
     
    string body = $@"
    {{
        ""username"": ""{username}"",
        ""password"": ""{password}""
    }}";
     
    HttpRequestMessage httpRequest = new HttpRequestMessage(HttpMethod.Post, "/auth/1/session");
    httpRequest.Content = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
     
    var response = client.SendAsync(httpRequest).GetAwaiter().GetResult();
    var responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
     
    var responseObject = JsonSerializer.Deserialize(responseContent);
     
    return responseObject.Token;

例 - HTTP クライアント

以下の例は、HTTP 要求を準備する方法を示しています。これは API キー認証とほぼ同じですが、ヘッダーで App の代わりに IBBSO を使用します。

REQUEST SAMPLES

 
    private static class IbssoResponse {
        public IbssoResponse() {
            super();
        }
     
        @JsonProperty("token")
        public String token;
     
        @JsonGetter("token")
        public String getToken() {
            return token;
        }
     
        @JsonSetter("token")
        public void setToken(String token) {
            this.token = token;
        }
    }
     
    String jsonBody = String.format("{\"username\":\"%s\",\"password\":\"%s\"}", "USERNAME", "PASSWORD");
     
    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), jsonBody);
     
    Request request = new Request.Builder()
            .url("BASE_URL" + "/auth/1/session")
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .post(requestBody)
            .build();
     
    OkHttpClient httpClient = new OkHttpClient().newBuilder().build();
    Response response = httpClient.newCall(request).execute();
    String responseBody = response.body().string();
    System.out.println(responseBody);
     
    IbssoResponse ibssoResponse = new ObjectMapper().readValue(responseBody, IbssoResponse.class);
     
    return ibssoResponse.token;

 
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
     
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("IBSSO", "TOKEN");
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

例 - API ライブラリ

Infobip API クライアントライブラリ (opens in a new tab) を使用する場合は、API キー認証と同じ要素が必要ですが、App の代わりに IBBSO を使用します。

csharp

 
    var configuration = new Configuration()
    {
        BasePath = "BASE_URL",
        ApiKeyPrefix = "IBSSO",
        ApiKey = "TOKEN"
    };

OAuth 2.0 (英語)

このタイプの認証は最も安全なオプションであり、ほぼ業界標準です。IBSSO トークンを使用する場合と同様に、別のエンドポイントから取得したアクセストークンを使用します。

この方法に関するいくつかの重要な事実を次に示します。

応答で返されたアクセストークンは、同じ応答で秒単位で指定された制限時間内に期限切れになります。
Infobip は、リソースと承認サーバーの両方として機能します。
トークンの有効期限が切れたら、新しいトークンを作成する必要があります。トークンの自動取得はありません。

詳細については、公式の OAuth 2.0 (opens in a new tab) 仕様を参照してください。

OAuth 2.0 の使用方法

別のエンドポイント (opens in a new tab)からアクセストークンと有効期限を取得するための呼び出しを行います。
トークンの有効期限が切れるまで、後続のすべての呼び出しの権限付与ヘッダーに Bearer とトークンを含めます。 Authorization: Bearer eyJraWQiOiI5d29rWGRoSSIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJzdWIiOiJERDIwMjAiLCJpc3MiOiJpbmZvYmlwLmNvbSIsImV4cCI6MTYzMzAwNDQwNiwiaWF0IjoxNjMzMDAwODA2LCJqdGkiOiJiMmJmODgyMS01OTcxLTRiOTMtYWVmNy0zM2QwMDNkMjIxNjcifQ.KvIIOmCKJETiB6xKOqBxvZYnYOa8RAulYhChBEmI4Os

HTTP 要求

OAuth2 トークンの作成 (opens in a new tab)

OAuthトークンの取得

IBSSO トークンと同様に、API 呼び出しを行う前に、まずトークンを取得する必要があります。

REQUEST SAMPLES

 
    private static class OauthResponse {
        public OauthResponse() {
            super();
        }
     
        @JsonProperty("access_token")
        private String accessToken;
        @JsonProperty("expires_in")
        private String expiresIn;
     
        @JsonGetter("access_token")
        public String getAccessToken() {
            return accessToken;
        }
     
        @JsonSetter("access_token")
        public void setAccessToken(String accessToken) {
            this.accessToken = accessToken;
        }
     
        @JsonGetter("expires_in")
        public String getExpiresIn() {
            return expiresIn;
        }
     
        @JsonSetter("expires_in")
        public void setExpiresIn(String expiresIn) {
            this.expiresIn = expiresIn;
        }
    }
     
    HttpPost post = new HttpPost(BASE_URL + "/auth/1/oauth2/token");
    List  nvps = new ArrayList();
    nvps.add(new BasicNameValuePair("client_id", username));
    nvps.add(new BasicNameValuePair("client_secret", password));
    nvps.add(new BasicNameValuePair("grant_type", "client_credentials"));
     
    post.setEntity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
     
    DefaultHttpClient httpClient = new DefaultHttpClient();
    HttpResponse response = httpClient.execute(post);
    System.out.println(response.getStatusLine());
     
    String responseJson = EntityUtils.toString(response.getEntity());
    System.out.println(responseJson);
     
    OauthResponse oauthResponse = new ObjectMapper().readValue(responseJson, OauthResponse.class);
     
    return oauthResponse.accessToken;

 
    public class OauthResponse
    {
        [System.Text.Json.Serialization.JsonPropertyName("expires_in")]
        public int ExpiresIn { get; set; }
     
        [System.Text.Json.Serialization.JsonPropertyName("access_token")]
        public string AccessToken { get; set; }
    }
     
    string username = "USERNAME";
    string password = "PASSWORD"; 
     
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
     
    var dict = new Dictionary();
    dict.Add("client_id", username);
    dict.Add("client_secret", password);
    dict.Add("grant_type", "client_credentials");
     
    HttpRequestMessage httpRequest = new HttpRequestMessage(HttpMethod.Post, "/auth/1/oauth2/token");
    httpRequest.Content = new FormUrlEncodedContent(dict);
     
    var response = client.SendAsync(httpRequest).GetAwaiter().GetResult();
    var responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
     
    var responseObject = JsonSerializer.Deserialize(responseContent);
     
    var accessToken = responseObject.AccessToken;

例 - HTTP クライアント

以下の例は、ヘッダーを使用して HTTP クライアント要求を準備する方法を示しています。

REQUEST SAMPLES

 
    Request request = new Request.Builder()
            .url("BASE_URL" + "/sms/2/text/advanced")
            .addHeader("Authorization", "Bearer " + accessToken)
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .post(body)
            .build();

 
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("BASE_URL");
     
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ACCESS_TOKEN");
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

例 - API ライブラリ

以下の例は、ヘッダーを含むHTTPリクエストを準備する方法を示しています。

csharp

 
    var configuration = new Configuration()
    {
        BasePath = "BASE_URL",
        ApiKeyPrefix = "Bearer",
        ApiKey = "ACCESS_TOKEN"
    };

エラー

通常、ユーザー名またはパスワードが見つからないか無効な場合、応答として401 UnauthorisedHTTPステータスコードが表示されます。

json

 
    {
        "requestError": {
            "serviceException": {
                "messageId": "UNAUTHORIZED",
                "text": "Invalid login details"
            }
        }
    }

ライブラリの例外

ライブラリ (opens in a new tab)のいずれかを使用する場合は、必ずAPI例外を処理してください。

REQUEST SAMPLES

 
    try {
        SmsResponse smsResponse = sendSmsApi.sendSmsMessage(smsMessageRequest);
    } catch (ApiException apiException) {
        apiException.getCode();
        apiException.getResponseHeaders();
        apiException.getResponseBody();
    }

 
    try
    {
        var result = api.SendSmsMessage(smsRequest);
    }
    catch(ApiException apiException)
    {
        var errorCode = apiException.ErrorCode;
        var errorContent = apiException.ErrorContent;
    }

API 認証

基本的な

例 - HTTP クライアント

例 - API クライアント ライブラリ

基本認証の API スコープ

APIキー ヘッダー

例 - HTTP クライアント

例 - API クライアント ライブラリ

API キーの API スコープ

IBSSO トークン ヘッダー

IBSSOトークンの使用方法

HTTP 要求

IBSSOトークンの取得

OAuth 2.0 (英語)

OAuth 2.0 の使用方法

HTTP 要求

OAuthトークンの取得

エラー

ライブラリの例外

例 - API クライアントライブラリ

APIキーヘッダー

例 - API クライアントライブラリ

IBSSO トークンヘッダー