Difference between revisions of "Linden Lab Official:Registration API"

Second Life APIs

Overview

The Registration API (Reg API) enables you to register new Second Life users on your website, and set the location where they initially appear inworld after they log in. With the Reg API you can:

Create, manage, and track your community in Second Life.
Maintain your brand identity from your website through user registration and into Second Life.

Important limitations and conditions apply. For example, you must make clear that users are establishing a relationship with Linden Lab, separate from their relationship with you.

The Reg API is a simple REST-style web service. Pass information to and from the service in LLSD XML documents. Linden Lab provides libraries to parse and encode LLSD in Perl, PHP, Python, and Ruby; see Reg API Examples.

What the Reg API can do

Use the Reg API to create Second Life accounts during the user registration process on your website. You can customize the Second Life registration process to capture additional information or fit your registration process. When a user registers, they choose a unique Second Life name and password. Registration provides Linden Lab with the same information provided through standard registrations on the Second Life website. At the end of registration, your customer must download the Second Life client, install, and run it. At that time, they will be registered with the account they created on your website and will start Second Life in a location you specify.

With the Reg API, you can:

Register Second Life Residents from your website and track them.
Provide customized and branded registration.
Send them to a location of your choice when they first log in to Second Life.
Limit accounts to your estate.
If Linden Lab has granted permission, limit name selection, or create accounts with a custom name. You must request this permission separately; see Custom Name Program for more information.
Provide registrations for your organization with internal access only, for example using an internal web site.

What the Reg API cannot do

The Reg API does not provide the ability to:

Assign new Residents to groups
Provide inventory, create attachments, or control the Resident's outfit
Alter the appearance of the Viewer.
Automatically balance load on a sim. Instead, use the Reg API to selectively set the starting location based on data sent from an LSL script in each location.

The Reg API does not prohibit you from setting a starting location to land that you don't own. You must make sure that the owner of the landing location agrees to have the new Residents arrive there if you don't own the land.

How to participate

To request participation in the beta Registration API program, submit the Registration API Request Form. Linden Lab will contact you by email after reviewing your application.

Important notices

The RegAPI is a beta program that requires some technical proficiency to use successfully. Linden Lab does not currently provide support or technical advice on its use.

Accounts with Reg API capabilities that have not signed up at least one account within 90 days of receipt of the capabilities will have their Reg API access removed.

All participants in the Reg API program must abide by Linden Lab's API Terms Of Service.

Discussion and support

Use the talk page to post questions about the RegAPI.
Use the RegAPI mailing list to share information and send inquiries about the Reg API.
Although Linden Lab does not provide technical support for the Reg API, you can purchase support from third-party providers; see Registration API Third Party Support.

General procedure

To use the Reg API:

Fill out and submit the Registration API Request Form. Linden Lab will respond by email.
Verify your capabilities using the capabilities form.
Make sure you have permission from the owner of the estate where your users will appear inworld. You must have permission of the landowner (except for Linden Lab Orientation Islands). If you have multiple registrations and need to send people to different locations, contact us to obtain additional assignments.
Create your registration web page
If using PHP, make sure the necessary libraries are installed and working (see http://uk.php.net/phpinfo )
Test your registration application:
- Register several new users.
- If you aren't getting results you expect, check the error code.
- Create registrations to test the most common error codes and verify that you receive and properly handle them appropriately.

WHEN TESTING

If you are using the Reg API to sign up registrants on the main grid, users under 18 will not be allowed to register, since they are not permitted on the Main Grid. Therefore, when testing, use a birth date that makes the registrant older than 18 years.

Use an email address that does not currently exist in Second Life. If a user has already registered with an email address, the Reg API will return error 95, email exists. If you trap errors, you will see this error code, but if not, registration will simply fail.

Using capability URLs

Reg API capabilities represent permissions to perform certain actions. The Reg API grants capabilities with capability URLs of the form:

https://cap.secondlife.com/cap/0/UUID

Where UUID is the UUID (universally unique identifier) granted for the specific capability.

For example:

 https://cap.secondlife.com/cap/0/2897456b-6959-473e-9b94-36d8cec1b9c3

The Reg API provides capability URLs for the following operations:

create_user - create a new user
check_name - indicates whether a user can be registered with a given Second Life first name and last name
get_last_names - returns last names and corresponding IDs with which you are able to register new users.
get_error_codes - returns the set of error codes

For more information on these operations, see the Registration API Reference.

For example, consider the example capabilities form provided on the Second Life website. It requests a description of the capabilities currently granted to you.

The form POSTs your "first_name", "last_name" and "password" to https://cap.secondlife.com/get_reg_capabilities to get your capabilities. The actual HTML looks like this:

First Name	<input name='first_name'>
Last Name	<input name='last_name'>
Password	<input name='password' type='password'>

<input type='submit' value="Get Capabilities">

</form></html4strict>

When you submit a form such as this, the Reg API returns an XML document that looks like this:

 <map>
   <key>get_error_codes</key>
   <string>https://cap.secondlife.com/cap/0/e2fd05e0-d4f0-4f04-8805-fdc1bd4e9ea2</string>
 </map>

</llsd></xml>

This example shows that you have the "get_error_codes" capability. If instead you had been granted more capabilities, the document would look something like this:

<llsd>
  <map>
    <key>create_user</key>
    <string>https://cap.secondlife.com/cap/0/35ff3b8c-a30d-4d18-b29a-e3f7f6c79cb6</string>
    
    <key>check_name</key>
    <string>https://cap.secondlife.com/cap/0/6e528ba1-a8b0-4f6b-8b56-362ee6f5cef8</string>
    
    <key>get_last_names</key>
    <string>https://cap.secondlife.com/cap/0/be4e4d2e-c00a-46cd-bb8d-d17cb8e92c9b</string>
    
    <key>get_error_codes</key>
    <string>https://cap.secondlife.com/cap/0/e75f81a5-b7da-4480-8f95-b1cf9d2d680f</string>
  </map>
</llsd>

Of course, these example capabilities URLs don't actually work.

Using LLSD with the Reg API

Use LLSD XML data format to send and get information to and from capability URLs. Here is an example of a typical LLSD XML message:

  <map>
    <key>dob</key><string>1987-07-06</string>
    <key>start_region_name</key><string>da boom</string>
    <key>username</key><string>mistaht</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>password</key><string>123456</string>
    <key>email</key><string>ben@ben.com</string>
  </map>
</llsd></xml>

This document represents a map (hash) containing keys for:

dob
start_region_name
username
last_name_id
password
email

This document is a typical LLSD XML message that you might POST to the "create_user" capability URL to create a new user.

The LLSD specification specifies many different data types: Map, Array, String, Integer, Float, Date, and so on. Each data type corresponds to a native object type in most languages.

The LLSD XML libraries handle most of the work of encoding native objects into LLSD XML and vice-versa. For example, you can use the Ruby library as follows:

require 'LLSD'

native_obj = 123
llsd_xml = LLSD.to_xml(native_obj) # returns <llsd><integer>123</integer></llsd>
returned_native_obj = LLSD.parse(llsd_xml) # returns native ruby integer, 123

If you have problems encoding and decoding LLSD, look at the actual LLSD XML being sent and received to start debugging.

Limiting accounts to an estate

You can use the Reg API to limit registrants to the estate of the registrar (the account that controls the registration). You must use the estate ID for the limited_to_estate parameter when creating the account. See create_userfor detals.

To find your estate Code (as of March 16th 09):

Ctrl-Alt-⇧ Shift-D to enable the extra pull-down advanced menu.
Then use Advanced > View Admin Options (near the bottom).
From new pull-down menu Admin, select God Tools.
Look at the Region tab. The Estate ID is listed there.

Accounts can't access estate

If you're setting registration to 'restrict to estate' and people can't enter your estate, realize that if you've set access controls to require group membership to enter, the new registrations won't be able to enter your estate.

If you want to restrict access to groups, you may need to subdivide and create a parcel that has no restrictions on your estate and set your landing area there, then add them to the group(s) to be able to access the rest of the Estate.

Guidelines and tips

Make sure you're using the account that was enabled for the Registration API to create accounts.
You must use the Registration API to create additional accounts, not the Viewer or the secondlife.com registration page.
Verify you've including your capabilities url (get it at What are Capability URLs) and properly set up your account and the location in the script
Check for error codes
Join the Reg API mailing list for additional information and troubleshooting help.

When using capability URLs, follow these guidelines:

Add code to capture and display returned error codes; this will assist you in troubleshooting problems.
Do not hard-code your capabilities URLs. Either code your capabilities URLs as constants, or better yet, obtain them at run-time. Capability URLs will expire eventually, so fresh ones are always better.
Keep your capability URLs secret! The capabilities granted to you are only meant for you. A capability URL is sensitive much like a password. Moreover, Linden Lab tracks the use of each capability.

If using PHP:

The LLSD library has not been tested with PHP5, and is known NOT to work with many common configurations of PHP5. We expect to have and improved version of it available soon, which will be compatible with PHP4 and PHP5. In the meantime, if you have to use PHP5, some folks report using this adapter successfully: http://alexandre.alapetite.net/doc-alex/domxml-php4-php5/
Or if you like living dangerously, try RegAPI_for_PHP5.
Make sure the Curl library is installed and running.

@@ Line 72: / Line 72: @@
 Reg API [[Capabilities|capabilities]] represent permissions to perform certain actions. The Reg API grants capabilities with ''capability URLs'' of the form:
- <nowiki>https://cap.secondlife.com/cap/0/</nowiki>''UUID''
+{{Command|https://cap.secondlife.com/cap/0/''UUID''}}
 Where ''UUID'' is the UUID (universally unique identifier) granted for the specific capability.
@@ Line 94: / Line 94: @@
 The form POSTs your "first_name", "last_name" and "password" to https://cap.secondlife.com/get_reg_capabilities to get your capabilities.  The actual HTML looks like this:
-<pre>
+<html4strict><form action="https://cap.secondlife.com/get_reg_capabilities" method="POST"><br />
-<form action="https://cap.secondlife.com/get_reg_capabilities" method="POST"><br />
 <table>
 <tr><td>First Name</td><td><input name='first_name'></td></tr>
@@ Line 105: / Line 104: @@
 <tr><td align='center' colspan=2><input type='submit' value="Get Capabilities"></td></tr>
 </table>
-</form>
+</form></html4strict>
-</pre>
 When you submit a form such as this, the Reg API returns an XML document that looks like this:
-<pre>
+<xml><llsd>
-<llsd>
    <map>
      <key>get_error_codes</key>
      <string>https://cap.secondlife.com/cap/0/e2fd05e0-d4f0-4f04-8805-fdc1bd4e9ea2</string>
    </map>
-</llsd>
+</llsd></xml>
-</pre>
 This example shows that you have the "get_error_codes" capability. If instead you had been granted more capabilities, the document would look something like this: