Signing up to the Developer Portal (authentication URL)

If your Catalog is using an authentication URL to authenticate user log in to the Developer Portal, you can use Developer Portal REST API calls to sign users up.

To complete the steps described in this topic, you need an environment capable of sending HTTP requests and receiving HTTP responses. Here, the curl command is used in a command line interface to demonstrate the REST API calls. In your environment, make the same REST API calls as are made with curl commands in this topic.

To sign a user up to the Developer Portal, you complete one or other of the following steps:

Sign the user up directly. A new Developer organization is created with the user as its owner. The user account is activated immediately.
Sign the user up by invitation. You must complete the following steps:
1. Invite the user to join a Developer organization by making a REST API call. On successful completion of the call, an activation email is sent to the user, and the account is in a pending state until the activation is completed.
2. Obtain the user authentication information and activation REST API URL. The activation email contains authentication information in base64 encoded form. You must base64 decode this authentication information.
3. Activate the user account. Make a REST API call to activate the account, supplying the decoded authentication information.

These steps are described in the following sections:

Signing the user up to the Developer Portal directly

To sign the user up directly, make the following REST API call:

curl -k -v -H "X-IBM-APIManagement-Context: provider_org.catalog" -H "Content-Type: application/json" -X POST -d \
'{"username":"user_name","password":"password","firstName":"first_name","lastName":"last_name","organization":"dev_org_name"}' \
https://management_service_address/v1/portal/users/register

where:

provider_org is the name of the provider organization of the Developer Portal to which the user is to be signed up.
catalog is the name of the Catalog of the Developer Portal to which the user is to be signed up.
user_name is the user name of the user that you want to sign up. The user name is the user ID with which the user will log in to the Developer Portal.
password is the initial login password. The password must contain characters from three of the following four categories: uppercase, lowercase, numeric, and punctuation (for example, !, $, #, %).
(optional) first_name is the user's first name.
(optional) last_name is the user's last name.
(optional) dev_org_name is the name that will be assigned to the user's Developer organization. The default name is the email_address value.
management_service_address is the host name or IP address of your API Connect Management service.

On successful completion of the call, the account is active and the user can log in to the Developer Portal.

Inviting the user to join a Developer organization

To invite a user to join a Developer organization, make the following REST API call:

curl -k -v -u "dev_org_owner_id:dev_org_owner_password" \
-H "X-IBM-APIManagement-Context: provider_org.catalog" -H "Content-Type: application/json" \
-X POST -d '{"name":"email_address", "roles":[array_of_roles]}' \
https://management_service_address/v1/portal/orgs/dev_org_id/members

where:

dev_org_owner_id is the login ID of the owner of the Developer organization that the user is being invited to join.
dev_org_owner_password is the login password of the owner of the Developer organization that the user is being invited to join.
provider_org is the name of the provider organization of the Developer Portal to which the user is to be signed up.
catalog is the name of the Catalog of the Developer Portal to which the user is to be signed up.
email_address is the email address of the user that you want to invite.
(optional) array_of_roles is a JSON array specifying the roles that you want to assign to the user. The following roles are available:
- "developer": Can create and edit applications, manage client keys and subscribe to Plans.
- "viewer": Can only view applications and application activity.
For example:
```
"roles":["developer"]
```
If omitted, the default value is ["developer"].
management_service_address is the host name or IP address of your API Connect Management service.
dev_org_id is the ID of the Developer organization.
To obtain the ID of the Developer organization, make the following REST API call, which lists the details of the Developer organizations of which the authenticated user is a member:
```
curl -k -v -u "dev_org_user_id:dev_org_password" \
-H "X-IBM-APIManagement-Context: provider_org.catalog" \
-H 'Content-Type: application/json' -X GET https://management_service_address/v1/portal/orgs
```

On successful completion of the invite operation, an activation email is sent to the specified email address.

Obtaining the user authentication information and activation REST API URL

The invitation email contains an activation link URL with an activationToken parameter. The activation link has the following format:

https://portal_url/?q=ibm_apim/activate/x&activationToken=activation_token

To obtain the user authentication information and the activation REST API URL, you must decode the activation token by using a base64 decoder.

The following example shows the format of the decoded activation token:

{"url":"https://myhost.com/v1/portal/users/48663d86e4b0e688ee1cded4/activate",
"username":"!BASE64_SIV_ENC!_AQZ+4GefJbUFPRVVbZb4M/fGgkeyHi9zZT4I8RKA3+IRAAAAGKc0NUo0lvPq2VxBHalDyYRHKdbQWoCs3dkCf43e9WoQ",
"authentication":{"username":"58651bdfe4b0e687ee1cc7a1/58651d9ce5b0e687ee1cc6b0/jS2lD1fW8nQ8zW0dE3cS6eI3hU1hP5oN3jU8dK7sP8",
"password":"CG+YUlm1cLITToGCfciSeVMdFeV7BQMxvsR0XxZbkc"},
"providerContext":{"orgID":"5819e9e6e4b0e645ee1bfdeb","environmentID":"58651bdfe4b0e687ee1cc7a1"}}

In the decoded token, the authentication field contains the authentication data in the following format:

"authentication":{"username":"encoded_user_name","password":"encoded_password"}

The url field contains the activation REST API URL in the following format:

"url":"activation_url"

The activation REST API URL has the following format:

https://management_service_address/v1/portal/users/user_id/activate

where:

management_service_address is the host name or IP address of your API Connect Management service.
user_id is a unique user ID string.

Note the encoded_user_name, encoded_password, and activation_url values because they are required in the REST API call that you use to activate the user account.

Activating the user account

Make the following REST API call:

curl -k -v -H "Content-Type: application/json" -H "X-IBM-APIManagement-Context: provider_org.catalog" \
-u 'encoded_user_name:encoded_password' -X POST -d \
'{"username":"user_id","password":"password","firstName":"first_name","lastName":"last_name"}' activation_url

where:

provider_org is the name of the provider organization.
catalog is the name of the Catalog.
encoded_user_name and encoded_password are the authentication information values that you noted in Obtaining the user authentication information and activation REST API URL.
activation_url is the activation REST API URL that you noted in Obtaining the user authentication information and activation REST API URL.
user_id is the user ID with which the user will log in to the Developer Portal.
password is the login password. The password must contain characters from three of the following four categories: uppercase, lowercase, numeric, and punctuation (for example, !, $, #, %).
(optional) first_name is the user's first name.
(optional) last_name is the user's last name.

On successful completion of the activation REST API call, the user can log in to the Developer Portal user interface with the specified user ID.