Register an App for API Access
To register an app for the IBM® Graph API, complete the following steps:
- 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.
- Go to .
- Register a new app with required permissions:
- Click Create on the App registrations page.
- On the Create app registration page, enter a name for the app.
- Click Add service and permission.
- 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.
- 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.
- 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.
- 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.
- 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:
- Set the access token
URL.
https://identity.sp4c.storage-defender.ibm.com/connect/token - Set the header.
Content-Type: application/x-www-form-urlencoded
- 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 toclient_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
- 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:
- Ensure
.NETversion 6 or later is installed. - 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 - Modify
Program.cs. Open theSP4CPublicApiTokenSamplefolder and find theProgram.csfile. 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; } } - Execute the following command to run the
project.
dotnet run - Access token output. The console will display:
[Access Token] eyJhbGc... [Scope] audit.read.all