Overview

In the Builder, you register clients for APIs. API Management is the management service used in these areas in YaaS:

  • create, update, and delete clients and services
  • create, update, and delete credentials of clients
  • update and delete credentials of services (Basic Authentication)
  • retrieve service scopes defined for a given project.

First, register a Project and add a Client. Develop your own Service and link it with your client. Then, add a Builder Module and wrap it with your service into a package. Now you are ready to publish and sell in the YaaS Market!


API Reference

/projects/{projectID}/services-scopes

This endpoint allows to get a complete set of service scopes defined for given project.

/projects/{projectID}/services-scopes

get

This endpoint allows you to get a complete set of service scopes defined for a given project.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_manage scope.

/projects/{projectID}/applications

DEPRECATED

/projects/{projectID}/applications

get

DEPRECATED
Returns all API applications.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_mange scope.

You can sort your results by the following fields: name, createdAt and modifiedAt.

post

DEPRECATED
Creates a new API application.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_mange scope.

/projects/{projectID}/applications/{applicationID}

DEPRECATED

get

DEPRECATED
Returns API application with the given ID.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_mange scope. Requested project must be the owner of requested application.

put

DEPRECATED
Updates API application with the given ID.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_mange scope. Requested project must be the owner of requested application.

delete

DEPRECATED
Deletes API application with the given ID.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_mange scope. Requested project must be the owner of requested application.

/projects/{projectID}/applications/{applicationID}/credentials

DEPRECATED

get

DEPRECATED
Returns API application with the given ID.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view scope.

post

DEPRECATED
Adds credentials to an application. There might be up to 2 credentials defined per application.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_mange scope.

/projects/{projectID}/applications/{applicationID}/credentials/{applicationId}

DEPRECATED

delete

DEPRECATED
Removes application credentials. Application must have at least one credentials defined.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_mange scope.

/projects/{projectID}/clients

/projects/{projectID}/clients

get

This endpoint allows you to get a complete set of clients defined for a given project.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_manage scope.
You can sort your results by the following fields: name, createdAt and modifiedAt.

post

Creates a new client.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope.

/projects/{projectID}/clients/{identifier}

get

Returns a client with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_manage scope. Requested project must be the owner of requested client.

put

Updates the client application with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope. Requested project must be the owner of requested client.

delete

Deletes client application with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope. Requested project must be the owner of requested client.

/projects/{projectID}/clients/{identifier}/credentials

get

Returns a client application with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view scope.

post

Generates a new pair of credentials (clientId, clientSecret) to a client application. You can define up to 2 pairs of credentials per client.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope.

/projects/{projectID}/clients/{identifier}/credentials/{clientId}

delete

Removes client credentials. Every client application must have at least one pair of credentials defined.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope.

/projects/{projectID}/services

/projects/{projectID}/services

get

Returns all services.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_manage scope.
You can sort your results by the following fields: name, createdAt and modifiedAt.

post

Creates a new service.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope.

/projects/{projectID}/services/{serviceID}

get

Returns service with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_view or hybris.api_manage scope. Requested project must be the owner of requested service.

put

Updates service with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope. Requested project must be the owner of requested service.

delete

Deletes service with the given identifier.

Security / Access Control:
To access this method, access token must be issued for the requested project and have hybris.api_manage scope. Requested project must be the owner of requested service.

/projects/{projectID}/services/{serviceID}/credentials

This endpoint allows you to set or delete pairs of credentials used by the proxy to call the service with Basic Authentication.

put

Sets credentials for the service for ALL regions. The proxy will use these credentials to perform HTTP Basic Authentication when calling the service. Warning: Following best security practices you should always set different credentials for each region!

To set the credentials the service sourceUrl MUST be defined with the secure protocol (https)!
Username complexity rules: length between 8 and 33 characters (inclusive).
Password complexity rules: at least one lowercase letter, at least one capital letter, at least one digit, length between 8 and 33 characters (inclusive).

Security / Access Control:
To access this method, access token must be issued for the project and have hybris.api_manage scope to manage this resource.

delete

Deletes service credentials for ALL regions. You can't replace the service's sourceUrl with an insecure (http) protocol URI while there are credentials defined for the service.

Security / Access Control:
To access this method, access token must be issued for the project and have hybris.api_manage scope to manage this resource.

/projects/{projectID}/services/{serviceID}/credentials/{region}

This endpoint allows you to set or delete pairs of credentials used by the proxy to call the service with Basic Authentication.

put

Sets credentials for the service. The proxy will use these credentials to perform HTTP Basic Authentication when calling the service. Currently, the accepted regions are : us and eu
Warning: Following best security practices you should always set different credentials for each region!

To set the credentials the service sourceUrl MUST be defined with the secure protocol (https)!
Username complexity rules: length between 8 and 33 characters (inclusive).
Password complexity rules: at least one lowercase letter, at least one capital letter, at least one digit, length between 8 and 33 characters (inclusive).

Security / Access Control:
To access this method, access token must be issued for the project and have hybris.api_manage scope to manage this resource.

delete

Deletes service credentials. You can't replace the service's sourceUrl with an insecure (http) protocol URI when there are credentials defined for the service.

Security / Access Control:
To access this method, access token must be issued for the project and have hybris.api_manage scope to manage this resource.


Events

For more information about events, see the PubSub service documentation.

The topic owner client is: core.api

TypeDescriptionSchemaPayload Example
clientCreatedThe client has been created.clientCreated_v1_3
 {"id":"toad.sample-client","name":"toad.sample-client","owner":"toad","modifiedAt":"2016-04-27T04:56:33.636+0000","createdAt":"2016-04-27T04:56:33.636+0000","redirectUris":["https://www.redirect.com/callback"],"requiredScopes":["hybris.manage","something.view"],"appType":"MULTI_TENANT_APP"} 
clientUpdatedThe client has been updated.clientUpdated_v1_1
 {"id":"toad.client","name":"toad.client","owner":"toad","displayName":"One for api-management","description":"One for api-management","modifiedAt":"2016-04-27T04:56:30.743+0000","createdAt":"2016-04-04T12:56:10.899+0000","redirectUris":["https://www.redirect.com/callback.html"],"appType":"UI_MODULE","moduleUrl":"https://something.org"} 
clientRemovedThe client has been removed.clientRemoved_v1_1
 {"id":"toad.sample-client","name":"toad.sample-client","owner":"toad","displayName":"One for mobile","description":"One for mobile","modifiedAt":"2016-04-27T04:56:35.614+0000","createdAt":"2016-04-27T04:56:33.636+0000","redirectUris":["https://www.redirect.com/callbackupdate"],"requiredScopes":["something.manage"],"appType":"MULTI_TENANT_APP","moduleUrl":"https://www.module.com/module.json"} 
serviceCreatedThe service has been created.serviceCreated_v1
 {"id":"552a1fa6-67a2-4c02-a0a1-opr6ec663f72","projectId":"toad","name":"nameless","version":"v1","type":"","secured":false,"publishedAt":"2016-04-27T04:56:38.092+0000","description":"","proxyUrl":"https://api.eu.yaas.io/hybris/nameless/v1","scopes":null,"documentationUrl":"","modifiedAt":"2016-04-27T04:56:38.092+0000","state":"DRAFT","authorizationRules":null,"quotas":[{"metricKey":"requests","path":"/request/*/check","methods":["POST","GET","PUT","DELETE","PATCH","HEAD","*"]}],"allScopes":[]} 
serviceUpdatedThe service has been updated.serviceUpdated_v1
 {"id":"552a1fa6-67a2-4c02-a0a1-opr6ec663f72","projectId":"toad","name":"nameless","version":"v1","type":"","secured":false,"publishedAt":"2016-04-27T04:56:38.092+0000","description":"","proxyUrl":"https://api.eu.yaas.io/hybris/nameless/v1","scopes":null,"documentationUrl":"","modifiedAt":"2016-04-27T04:56:39.589+0000","state":"DRAFT","authorizationRules":null,"quotas":[],"allScopes":[]} 
serviceRemovedThe service has been removed.serviceRemoved_v1
 {"id":"552a1fa6-67a2-4c02-a0a1-opr6ec663f72","projectId":"toad","name":"nameless","version":"v1","type":"","secured":false,"publishedAt":"2016-04-27T04:56:38.092+0000","description":"","proxyUrl":"https://api.eu.yaas.io/hybris/nameless/v1","scopes":null,"documentationUrl":"","modifiedAt":"2016-04-27T04:56:39.589+0000","state":"DRAFT","authorizationRules":null,"quotas":[],"allScopes":[]} 

Each event includes the schema key in its metadata section. This allows you to identify the version of the payload that the event contains.


Scopes in API Management Service

The API Management service is protected with these Scopes:

  • hybris.api_manage - Use this scope to manage services and clients data.
  • hybris.api_view - Use this scope to view services and clients data.

If the respective values are not passed in the access token, the service returns an error 403 status code for the given request. For more information, see the API Management service API Reference, and the Request Headers.


Clients

A Client in YaaS is defined by the OAuth 2.0 Authorization Framework. Clients ask for the access to the protected resources, get the tokens, and use them to interact with YaaS APIs:

graph LR B{client}--> |1. requests access token| A[Authorization service] A[Authorization service]-->|2. grants access token| B{client} B-->|3. accesses protected resources| C[YaaS APIs]

When you register your client in the Builder, the unique values of the Client ID and Client Secret are automatically assigned. Each time the client requests access to the protected resources, it needs to authenticate with these values. If the resource owner grants the relevant permissions, the authorization service sends the response with the access token. Otherwise, it returns an informative error code.

Use these parameters attached to the client in requests for access tokens:

  • Client ID and Client Secret to authorize a service with the Client Credentials Grant
  • Client ID, Client Secret, and redirect_uri to authorize a Single Page Application with the Implicit Grant. Note that the redirect URI in your client's settings must match the value of the redirect_uri parameter that you pass in the authorization request.

Set Up a Project and Create a Client if you have not previously done so. Your Client ID and Client Secret are now available. In the Builder, go to Projects > {Your project} > Clients > {Your client} > Client Authorization. Use them in the requests for access tokens. In this scenario, the further interactions with YaaS services are limited to the context of the parent project (tenant). You cannot view or manage any secured data outside this tenant. For example, if your access token is issued in the scope of hybris.tenant=myshop1, you cannot modify products in the project myshop2.

Play around with various services and get more confident with the YaaS environment. As your experience grows, create your own service. Find out how in the Wishlist Tutorial section of the Getting Started. You need to link a client to your service and allow it to interact within YaaS environment. If you protect your service with scopes, attach them to your client. In the Builder, go to Projects > {Your project} > Clients > {Your client} > Required scopes > Manage required scopes, select them from My project scopes and Save your changes. This allows you to include the scopes in requests for access tokens.

Take full advantage of the platform and include your service in a package. Use the authorization data of the client linked with this service to acquire access tokens on behalf of the tenants that subscribe to the package. Send the relevant hybris.tenant=$tenant scope in your request to the OAuth2 service. In this scenario, your service can interact with YaaS APIs in the context of the subscribed tenant.

Example

The project named deer subscribes to a package that includes a service created by developers from the project horse. When the service requests an access token with the hybris.tenant=deer scope, it will receive it:

sequenceDiagram "horse" (tenant A)->>Service A: develops Service A->>Package A: is included in "deer" (tenant B)->>Package A:subscribes to Service A->>Authorization Server: requests access token with the scope="hybris.tenant=deer" Authorization Server->>Service A: Access Token Service A->>Service Q: interacts in the context of Project "deer", for example reads orders

Note that within a project you have access to your own services without package subscriptions.

For more information, see the Key Concepts in YaaS and Scopes and Subscriptions.


Service Blocking Rules

Blocking rules, or quotas, play an essential role in the availability and management of a service. They allow you to control the resources that you offer to your customers.

The service owner defines the quotas in the definition of the service. Together with the data gathered during the analysis of metrics processed by the YaaS components, they are translated into specific rules. The API Proxy verifies these rules, and the calls are blocked once the relevant quota is reached. For more information, see the API Proxy FAQs.

As a developer, you need to make sure that your service logs the custom values that are used for blocking rules. For example, if your service allows the users to add products, and you limit the number of products per tenant (project), you must be able to store the current number of products in your logs.

Example

Define the quotas in the Builder:

  1. Go to: Projects > {My Project} > Services > {My Service} > Blocking Rules. Select the + Blocking rule. This screen displays:

    Create Blocking Rule

  2. Provide these parameters:
    • Metric key - This field is required and specifies the key of the metric used to limit the quota, such as max-storage-mb-metric. The maximum length is 128 characters. This needs to be consistent with the metric key defined for the package that includes your service.
    • Methods – This field is required and specifies the standard HTTP methods to be secured, such as PUT and POST. Use the * wildcard to secure all methods.
    • Path – This field is required and specifies the secured path to your resource. Use path expressions and the * wildcard. For example, /data/* secures everything below the /data path.
  3. Save your changes.
The example translates into this rule: if a tenant that uses your service reaches the specified quota, the blocking rule for the path /data/* is triggered for the PUT and POST method. The subsequent calls are blocked.

Note that the created blocking rules must be in line with the billing plan of the package that includes your service.

Currently, the publishing of packages is restricted. For more information, see the YaaS Market.


Register Your Service in YaaS Personal Data Registry

If your service handles personal data, you must register it in the central YaaS personal data registry. You can register each of the regions in which you deployed your service independently.

To register your service in the YaaS personal data registry, send a PUT request to the /projects/{projectID}/services/{serviceID} endpoint of the API Management service. Provide the regions in which the service handles personal data as the value of the personalData body parameter.

This is a sample request to the /projects/{projectID}/services/{serviceID} endpoint of the API Management service that updates the service's description and indicates that it handles the users' personal data in the EU and the US regions. Line breaks are added for better readability.


curl -X PUT "<a href="http://api.eu.yaas.io/hybris/api-management/v1/projects/myproject/services/amazingservice"">http://api.eu.yaas.io/hybris/api-management/v1/projects/myproject/services/amazingservice"</a> \
-H 'Authorization: Bearer ACCESS_TOKEN_HERE \
-H 'Content-Type: application/json' \
-d '{"description":"This is a new description of my amazing service","personalData":["EU", "US"]}'

The request must include an access token issued for the project that is the owner of the service. The token must have the hybris.api_manage scope.

If your service handles personal data, you must make sure it can respond to the events published by the Transparency service.


Multiple Credentials of Clients

Client credentials are bound with a client in your project and can be linked to multiple services. This is manageable in the Builder. Compromising the credentials causes serious security threat. The API Management service provides a clean process for replacing credentials with no downtime period. You can easily generate a new pair of the authorization data and change them in your service. Deploy the secure version and remove the compromised credentials. This can be managed in the Builder, go to: Projects > {Your project} > Services > {Your service} > Client > {Your Client} > Client Authorization. Optionally, follow the steps in this tutorial.

Use this functionality in your credentials rotation policy.

Your client must have at least one pair of credentials. The maximum number is two pairs per client.


Introduction to Tutorials

Tutorials are designed in a way that you can check the API Console and interactively learn the API. Follow the interactive tutorial and see the real-life responses from the API Management service.


Add a Client

In this tutorial, use credentials provided in the Quick Setup section to get an access token, and add a client in a project.

If you use the credentials of a client from your existing project, make sure the hybris.api_manage scope is included in its required scopes.

1. Get all your variables in one place

These are the variables used in the tutorial:

clientId = {{clientId}};
clientSecret = {{clientSecret}};
tenant = {{projectId}};
scopesRequired = 'hybris.api_manage';

The scope hybris.api_manage allows you to perform GET and POST requests in the API Management service. The parameter tenant reflects the parent project of the client.

2. Get an access token from the OAuth2 service

Create an API client for the OAuth2 service:

API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');

Now retrieve the access token:

AccessToken = oAuth2Service.token.post({
'client_id' : clientId,
'client_secret': clientSecret,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': scopesRequired
});

When the access token is successfully issued, the service returns a 200 status code. Expand the response body and verify if the scope includes hybris.api_manage. For more information about authorization grants, see the OAuth2 API Docs.

Make the calls simpler and the code cleaner by assigning the access token to a variable:

access_token = AccessToken.body.access_token;

3. Add a client

Create an API client for the API Management service:

API.createClient('apimanagenentService',
'/services/apimanagement/v1/api.raml');

Create a body object and send the request:

app_obj = apimanagenentService.projects.projectID(tenant).clients.post(
{
  "name": "sample-tutorial-app",
  "appType": "SINGLE_TENANT_APP"
}, {
  headers: {
  'Authorization': 'Bearer ' + access_token,
     'Content-type' : 'application/json'
                      }
}
)

When the client is successfully added to your project, the service returns a 201 status code. Expand the response body to reveal the client ID and link. The ID is created with the following naming convention: <project_identifier>.<client_name>.

For more information about error codes, see the API Reference.


Manage Multiple Credentials for a Client

In this tutorial you will add new credentials to your client and later remove a selected pair. Go to the Builder and retrieve:

  • the Project ID (Identifier): Projects > {My project} > Administration
  • the Client ID (Identifier): Projects > {My project} > Clients > {My client}.

Add credentials to your client

Request

To add credentials to your client you need:

  • Method: POST
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/clients/{clientID}/credentials
  • Headers:
    • Authorization: This sends a valid OAuth2 access token.
  • URL Parameters:
    • {projectID} - This is the identifier of the current project.
    • {clientID} - This is the identifier of the current client.

Example

The following is an example of how to add credentials to a client:

curl -i -X POST -H "Authorization: Bearer 9o79bcea-1ac0-4752-55ae-pl59e8d09a25" https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/clients/photoworks.myclient/credentials

Response

The successful response returns a 201 Created status code.

Retrieve your Client Authorization data

Request

To retrieve the authorization data you need:

  • Method: GET
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/clients/{clientID}/credentials
  • Headers:
    • Authorization: This sends a valid OAuth2 access token.
  • URL Parameters:
    • {projectID} - This is the identifier of the current project.
    • {clientID} - This is the identifier of the current client.

Example

The following is an example of how to retrieve the client authorization data:

curl -i -H "Authorization: Bearer 9o79bcea-1ac0-4752-55ae-pl59e8d09a25" https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/clients/photoworks.myclient/credentials

Response

The successful response returns a 200 status code and information about credentials pairs:

[{"clientId":"JdkJCHNYpqYnmkrJY0L2EPbhHOJuhsjD","clientSecret":"NrkD9zkgHPrHDL09"},
{"clientId":"eylvGxBuHhZHmuKLfR2oHumSiK0PoAVM","clientSecret":"Gd61BgdUSv4GVUXa"}]

Delete your Client Authorization data

Request

To delete the authorization data you need:

  • Method: DELETE
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/clients/{clientID}/credentials/{clientId}
  • Headers:
    • Authorization: This sends a valid OAuth2 access token.
  • URL Parameters:
    • {projectID} - This is the identifier of the current project.
    • {clientID} - This is the identifier of the current client.
    • {clientId} - This is the clientId of the specified client that you want to remove.
The parameters clientID and clientId are case-sensitive. They refer to two separate identifiers.

Example

The following is an example of how to delete the client authorization data:

curl -i -X DELETE -H "Authorization: Bearer 9o79bcea-1ac0-4752-55ae-pl59e8d09a25" https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/clients/photoworks.myclient/credentials/JdkJCHNYpqYnmkrJY0L2EPbhHOJuhsjD

Response

The successful response returns a 204 No content status code.

When you run the request for retrieving the authorization data again, the response includes only one credentials pair, such as in the example:

[{"clientId":"eylvGxBuHhZHmuKLfR2oHumSiK0PoAVM",
"clientSecret":"Gd61BgdUSv4GVUXa"}]

For more information about error codes, see the API Reference.


Manage Basic Authentication Credentials

In this tutorial, you add Basic Authentication Credentials for your service that is deployed in two regions: eu and us. For more information about last mile security, see the Secure a Service document.

Follow the security best practices by always setting different credentials for each region!

To use this tutorial, you need the service's parent Project ID (Identifier) from the Builder: Projects > {My project} > Administration.

The parameter serviceID cannot be retrieved from the Builder. You need to call the API Management directly and list the services in your project to obtain it.

Request

To list the services in your project you need the following:

  • Method: GET
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/services
  • Headers:
    • Authorization - This includes a valid OAuth2 access token.
      To access this method, the access token must be issued for the requested project and have the scope hybris.api_view or hybris.api_manage.
  • URL Parameters:
    • {projectID} - This is the identifier of the project.

Example

The following is an example of how to list the services in your project:

curl -i -X GET -H "Authorization: Bearer 022-389496c2-e444-4046-b3e7-88f2dd36ee6e" https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/services

Response

The successful response returns a 200 OK status code. An example JSON content including the services of the requested project looks similar to the following:

[
  {
    "id": "7ou0jn3p92an",
    "projectId": "photoworks",
    "name": "tutorial",
    "publishedAt": "2015-08-13T09:00:03.562+0000",
    "sourceUrl": "https://sourceurl.us.com",
    "sourceUrls": [
      {
        "region": "us",
        "sourceUrl": "https://sourceurl.us.com"
      },
      {
        "region": "eu",
        "sourceUrl": "https://sourceurl.eu.com"
      }
    ],
    "description": "My service description",
    "proxyUrl": "https://api.eu.yaas.io/hybris/tutorial/v1",
    "proxyUrls": [
      {
        "region": "us",
        "urls": [
          "https://api.eu.yaas.io/hybris/tutorial/v1",
          "https://api.beta.yaas.io/hybris/tutorial/v1"
        ]
      },
      ...
    "regions": [
      {
        "region": "us",
        "secured": false
      },
      {
        "region": "eu",
        "secured": false
      }
    ],
    ...
]

The examples is this tutorial use the service with an id=7ou0jn3p92an parameter.

regions

The API Management service allows you to set the HTTP Basic Authentication credentials for both regions at the same time.

Request

To set the credentials you need the following:

  • Method: PUT
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/services/{serviceID}/credentials
  • Headers:
    • Authorization - This includes a valid OAuth2 access token.
      To access this method, the access token must be issued for the requested project and have the scope hybris.api_manage.
  • URL Parameters:
    • {projectID} - This is the identifier of the current project.
    • {serviceID} - This is the id of the service.
Use the parameter id obtained in the previous request.

Example

The following is an example of how to set the Basic Authentication credentials for the service with the id=7ou0jn3p92an for all regions:

curl -i -X PUT -H "Authorization: Bearer 022-389496c2-e444-4046-b3e7-88f2dd36ee6e" -H "Content-Type: application/json" -d '{"username": "username123ABC", "password": "password123ABC"}' "https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/services/7ou0jn3p92an/credentials"

Response

The successful response returns a 200 OK status code.

To improve the security of your services set different Basic Authentication credentials for each region.

Request

To set the credentials for a specified region you need the following:

  • Method: PUT
  • Request URL: http://api.eu.yaas.io/hybris/api-management/v1/projects/{projectID}/services/{serviceID}/credentials/{region}
    Currently, the accepted values for the parameter region are eu, or us.
  • Headers:
    • Authorization - This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested project and have the scope hybris.api_manage.
  • URL Parameters:
    • {projectID} - This is the identifier of the current project.
    • {serviceID} - This is the id of the service.

Example

The following example sets specific Basic Authentication credentials for the service with the id=7ou0jn3p92an for the eu region:

curl -i -X PUT -H "Authorization: Bearer 022-389496c2-e444-4046-b3e7-88f2dd36ee6e" -H "Content-Type: application/json" -d '{"username": "username456DEF", "password": "password456DEF"}' "https://api.eu.yaas.io/hybris/api-management/v1/projects/photoworks/services/7ou0jn3p92an/credentials/eu"

Response

The successful response returns a 200 OK status code.

When you list your services again, the value for the field secured is true:

...
    "regions": [
      {
        "region": "us",
        "secured": true
      },
      {
        "region": "eu",
        "secured": true
      }
    ],
...
Store the Basic Authorization credentials in a safe place. There is no way to retrieve them from the service details.

For more information about error codes, see the API Reference.


Glossary

TermDescription
clientAn OAuth2 client as defined in the OAuth 2.0 Authorization Framework. It is created within a project and can interact with services in YaaS.
projectCompany"s planned piece of work. It is required for registering clients and managing their credentials, and package subscriptions. It includes Staff members who have different User roles assigned.
scopesThe access rights to resources and operations in the service, such as hybris.product_manage, which enables you to create and modify products.
serviceSoftware running as a part of a hosted application on a server.
subscriptionA contract granting a user the right to use the API of the subrscribed service in a project.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.