Linden Lab Official:Registration API

Template:Needs Translation/es Template:Needs Translation/el Template:Needs Translation/fr Template:Needs Translation/he Template:Needs Translation/it Template:Needs Translation/ko Template:Needs Translation/nl Template:Needs Translation/hu Template:Needs Translation/no Template:Needs Translation/da Template:Needs Translation/sv Template:Needs Translation/tr Template:Needs Translation/pl Template:Needs Translation/pt Template:Needs Translation/ru Template:Needs Translation/th Template:Needs Translation/uk Template:Needs Translation/zh-Hans Template:Needs Translation/zh-Hant

Second Life APIs

• Registration API
  • Reg API Request Form
  • Examples
  • API Reference
  • Error Codes
  • Third Party Support
  • Custom Name Program
• Map API
  • Introduction
  • Basic Examples
  • Advanced Examples
  • API Reference
• Exchange Risk API
• Media Plugin API
• Live Data Feeds
• Search API
• Snapshot API
• World API

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.

Overview

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.

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. Information is passed 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 you can do

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 you can't 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

• Verify your capabilities. Enter the account assigned to the Registration API (check the email you got tellling you your account had been created). Get your capabilities here: What are Capability URLs.
• Although the documentation says the owner of the RegAPI account must be the same as the owner of the destination, that is not true; you can send registrants anywhere, but you should at least have permission of the owner (other than 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 you're using PHP, make sure the necessary libraries are installed and working (see http://uk.php.net/phpinfo )
• Verify that the Registration API works by using your web page to create a registration
• If you aren't getting results you expect, check if you're getting an error code
• Create registrations to test the most common error codes and verify that you receive and properly handle the RegAPI Error Codes.
• Please note that right now, the php scripts only work with PHP4. For more information, see RegAPI Tips
• Note: If you are using the RegAPI to sign up registrants on the main grid, users under 18 will not be allowed to register, as they are not permitted on the Main Grid.

Using capability URLs

Reg API capabilities represent permissions to perform certain actions. The API grants capabilities with capability URLs that look like this:

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

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.

After posting this information, the Reg API returns a document that looks like this:

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

This example shows the "get_error_codes" capability. To invoke this capability, follow the capability URL.

To register a new user (Resident), you must have been granted the capability to register users. If so, then the Reg API returns a document that looks 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.

The set includes 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, se Registration API Reference.

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:

<llsd>
  <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>

This document represents a Map (Hash) containing dob, start_region_name, username, last_name_id, password, and email as keys. This document is in fact a typical LLSD XML message that you might POST to the "create_user" capability url, in order 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 almost all of the dirty work encoding native objects into LLSD XML and vice-versa. For example, the ruby library can be used the following way:

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

As you can see, the libraries do most of the work encoding and decoding LLSD XML. If you, however, are running into problems, looking at the actual LLSD XML being sent and received is always a good place to start debugging.

Limiting accounts to an estate

The RegAPI can be used to limit registrants to the Estate of the Registrar (the account that owns the RegAPI). The Estate code (Estate ID) needs to be entered into the RegAPI (see Documentation: Capabilities POST Parameters, limited to Estate). To find your Estate Code (as of 24April08):

1. (Ctrl+Alt+Shift+D to enable the extra pull-down menu
2. Then use Client > View Admin Options. (near the bottom)
3. From new new pull-down menu Admin, select God Tools
4. 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 have to use the Registration API to create additional accounts, not the viewer or the SecondLife.com registration page.
• Make sure the Curl library is installed and running
• 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 RegAPI mailing list and use it for additional information or troubleshooting (To join, go to https://lists.secondlife.com/cgi-bin/mailman/listinfo/regapi).
• Our current 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/
• When you are testing the RegAPI, make sure that your birth date makes you older than 18 years and that you are using an email address that does not currently exist in Second Life - the latter will return error 95 (email exists - which you will see if you trap errors, but will cause registration to fail if you don't).
• We STRONGLY recommend you add code to capture and display returned error codes; this will assist you in troubleshooting problems.

When using capability URLs, follow these guidelines:

• 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.

References

• Obtaining the Registration API
• Custom Name Program

• Using the RegAPI
• RegAPI Documentation
• Sample Code for RegAPI
• Mini-DTDs for use with each call
• RegAPI Tips
• RegAPI Error Codes
• Third Party support for the RegAPI