Register an App for API Access

To register an app for the IBM® Graph API, complete the following steps:

  1. Access IBM Storage Protect for Cloud.

    Sign in to IBM Storage Protect for Cloud with your account. For more information, see Sign in to IBM Storage Protect for Cloud.

  2. Go to Administration > App registrations.
  3. Register a new app with required permissions:
    1. Click Create on the App registrations page.
    2. On the Create app registration page, enter a name for the app.
    3. Click Add service and permission.
    4. In the Add service and permission pane, select the services and corresponding permissions that you need to grant to the app, and then click Add.
      Note: For the services and permissions that you can grant to the app for using IBM Graph API, refer to Services and Permissions.
  4. Use a certificate or client secret as the app credentials. Credentials enable application to identify themselves to the authentication service when receiving tokens at a web address location (by using an HTTPS schema). For a higher level of assurance, we recommend using a certificate. Complete the following instructions to configure credentials:
    • The certificate serves as credentials that allow your application to authenticate itself, requiring no interaction from a user at run time. Refer to Prepare a Certificate for the Custom Azure App.
    • If you choose to use the client secret, you can generate a client secret effective within 1 year, 2 years, or 3 years. Client secret values cannot be entirely shown once they are saved.
  5. Obtain Application (Client) ID.

    After you have created the app registration, you can click the Copy button to copy the Application (client) ID value, which you can use to get an access token in the next step.

  6. Get an access token. Based on the credentials of your app registration, refer to the following steps to get an access token:
    • Use Client Secret: You need to send a POST request with the client ID, client secret, scope, and grant type. See the request and response samples in the linked section.
    • Use Certificate: You need to generate a JWT signed with your certificate and send a POST request with the client ID, client assertion (the signed JWT), scope, and grant type. See the example.
  7. Use the access token to call an API. For example, you can use the GET request to retrieve the audit records within a specific time range by using the access token:
    GET https://usea-graph.sp4c.storage-defender.ibm.com/sp4c/audit?startTime=2023-03-01T08:00:00Z&endTime=2023-03-02T08:00:00Z Authorization: Bearer YOUR_ACCESS_TOKEN

Services and Permissions

See the following table to know about the services and permissions that can be used for accessing API:
IBM Cloud Service Permission Usage
IBM Storage Protect for Cloud audit.read.all Get the audit records of activities in your IBM Storage Protect for Cloudtenant.
IBM Storage Protect for Cloud Dynamics 365 dynamics.readwrite.all Get job information from IBM Storage Protect for Cloud Dynamics 365.
IBM Storage Protect for Cloud Azure VMs, Storage, and Entra ID platformbackup.readwrite.all Get job information from IBM Storage Protect for Cloud Azure VMs, Storage, and Entra ID.
IBM Storage Protect for Cloud Microsoft 365 microsoft365backup.jobInfo.read.all Get job information from IBM Storage Protect for Cloud Microsoft 365.
microsoft365backup.subscriptionInfo.read.all Get the subscription consumption information of IBM Storage Protect for Cloud Microsoft 365.
IBM Storage Protect for Cloud Google Workspace gsuite.graph.read.all Getjob information from IBM Storage Protect for Cloud Google Workspace.

Client Secret

To obtain an access token by using a client secret in an app registration, complete the following steps to send a POST request:
  1. Set the access token URL.

    https://identity.sp4c.storage-defender.ibm.com/connect/token

  2. Set the header.
    • Content-Type: application/x-www-form-urlencoded
  3. Set the request body parameters.
    • client_id: Copy the application (client) ID from the app registration.
    • client_secret: Copy the saved client secret from the app registration.
    • scope: Set the scope, which is the assigned permission.
    • grant_type: Set to client_credentials.
      Request sample for getting access token by client secret:
      POST https://identity.sp4c.storage-defender.ibm.com/connect/token
      Content-Type: application/x-www-form-urlencoded
      client_id=edbdd4fa-0733-4cac-8a43-af4df3e97756
      &scope=audit.read.all
      &client_secret=3ZxGsm...wNG8wFrzY
      &grant_type=client_credentials
  4. Response details.
    • access_token: The token value.
    • expires_in: Indicates the token expiration in seconds.
      Response sample:
      { "token_type": "Bearer",
      "expires_in": 3600,
      "ext_expires_in":3600,
      "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkQ2MzA1NzRFRDdDRDdBR..." }
      Note: You can use Postman to test the POST request as described above.

Certificate

To obtain an access token by using a certificate in an app registration, complete following steps:
  1. Ensure .NET version 6 or later is installed.
  2. Create a new project. Use the following command to create a new project and add the required package:
    
    dotnet new console -o SP4CPublicApiTokenSample --framework net6.0
    cd ./SP4CPublicApiTokenSample
    dotnet add package System.IdentityModel.Tokens.Jwt --version 6.30.1
  3. Modify Program.cs. Open the SP4CPublicApiTokenSample folder and find the Program.cs file. Replace the file content with the following code:
    
    using System.IdentityModel.Tokens.Jwt;
    using System.Net.Http.Json;
    using System.Security.Claims;
    using System.Security.Cryptography.X509Certificates;
    using System.Text.Json.Serialization;
    using Microsoft.IdentityModel.Tokens;
    
    
    // Set your app registration information and certificate here
    const string CLIENT_ID = "YOUR_CLIENT_ID"; // Application (Client) ID
    const string SCOPES = "YOUR_SCOPE"; // Permission, e.g., "audit.read.all"
    const string CERTIFICATE_PATH = "YOUR_CERTIFICATE_PATH"; // Path to .pfx or .pem file
    const string CERTIFICATE_PASSWORD = "YOUR_CERTIFICATE_PASSWORD";
    
    
    const string IDENTITY_SERVICE_URI = "https://identity.sp4c.storage-defender.ibm.com/connect/token";
    const string AUDIENCE = "https://identity.sp4c.storage-defender.ibm.com/connect/token";
    
    
    var clientAssertionValue = GenerateClientAssertion();
    var token = await GetToken(clientAssertionValue);
    
    
    PrintToken(token);
    
    
    static string GenerateClientAssertion()
    {
    var certificate = new X509Certificate2(CERTIFICATE_PATH, CERTIFICATE_PASSWORD);
    var signingCredentials = new X509SigningCredentials(certificate);
    
    
    var claims = new List<Claim>()
    {
    new Claim("jti", Guid.NewGuid().ToString()),
    new Claim("sub", CLIENT_ID)
    };
    
    
    var jwtSecurityToken = new JwtSecurityToken(
    CLIENT_ID,
    AUDIENCE,
    claims,
    DateTime.Now,
    DateTime.Now.AddHours(1),
    signingCredentials);
    
    
    var clientAssertionValue = new JwtSecurityTokenHandler().WriteToken(jwtSecurityToken);
    return clientAssertionValue;
    }
    
    
    static async Task<SP4CTokenResponse?> GetToken(string clientAssertionValue)
    {
    var requestContent = new FormUrlEncodedContent(new Dictionary<string, string>
    {
    {"grant_type", "client_credentials"},
    {"client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"},
    {"client_assertion", clientAssertionValue},
    {"scope", SCOPES},
    });
    
    
    try
    {
    var client = new HttpClient();
    var response = await client.PostAsync(IDENTITY_SERVICE_URI, requestContent);
    
    
    if (response.IsSuccessStatusCode)
    {
    var token = await response.Content.ReadFromJsonAsync<SP4CTokenResponse>();
    return token;
    }
    else
    {
    throw new Exception($"Status code: {response.StatusCode}, Raw content: {await response.Content.ReadAsStringAsync()}");
    }
    }
    catch (Exception ex)
    {
    Console.WriteLine($"Get token failed: {ex}");
    return null;
    }
    }
    
    
    static void PrintToken(SP4CTokenResponse? token)
    {
    if (token == null)
    {
    return;
    }
    
    
    Console.WriteLine("[Access Token]");
    Console.WriteLine(token.AccessToken);
    Console.WriteLine("[Scope]");
    Console.WriteLine(token.Scope);
    }
    
    
    class SP4CTokenResponse
    {
    [JsonPropertyName("access_token")]
    public string? AccessToken { get; set; }
    
    
    [JsonPropertyName("expires_in")]
    public int ExpiresIn { get; set; }
    
    
    [JsonPropertyName("token_type")]
    public string? TokenType { get; set; }
    
    
    [JsonPropertyName("scope")]
    public string? Scope { get; set; }
    }
  4. Execute the following command to run the project.
    dotnet run
  5. Access token output. The console will display:
    
    [Access Token]
    eyJhbGc...
    [Scope]
    audit.read.all