View source for Linden Lab Official:Registration API

{{multi-lang}}

'''IMPORTANT: Use of the Registration API is subject to the [[API Terms of Use]].'''

{{:Web Services Portal/navigation}}
__TOC__
<br clear=all/>
== Overview == 
The Registration API (Reg API) enables you to register new Second Life users on your website when you require more than just the ability to send people to a location after they complete registration. If you want to have someone register an account and land at a specific location at login, then use [[SLURL#If_the_person_doesn.27t_have_Second_Life|DirectSLURL]].

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 [http://secondlife.com 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.

The Reg API is a simple [http://en.wikipedia.org/wiki/REST#RESTful_Web_services REST-style web service]. It sends and returns data in [[LLSD]] XML format.  Linden Lab provides libraries to parse and encode LLSD in Perl, PHP, Python, and Ruby; see [[Reg API Examples]].

In return for some programming effort, the Reg API enables you to:
* Limit accounts to your estate
* Create accounts with a custom name (with special permission from Linden Lab - see [[Custom_Name_Program]])
* Register multiple employees or students from your company or education institution from a single location or as part of your organization's website.

===Important Limitations and Conditions===
To qualify for the RegAPI Program, you must meet the following criteria:
* You must provide Linden Lab's Terms of Service as part of registration, in addition to any terms you require.
* All participants in Linden Lab's API program must abide by the [[Linden Lab Official:API Terms of Use|API Terms Of Use]].
* You must make clear that users are establishing a relationship with Linden Lab, separate from their relationship with you.  
* If your page is public, you must manage registration to comply with Linden Lab's policies about alternate accounts and registration verification. In general, Linden Lab will not approve use of the Reg API for public registration, since [[SLURL#If_the_person_doesn.27t_have_Second_Life|DirectSLURL]] is a preferable option.

For more information on the RegAPI see the Working Inworld blog post [https://blogs.secondlife.com/community/workinginworld/blog/2009/09/17/pocket-faq-creating-your-private-branded-workspace-with-reg-api Pocket FAQ: Creating Your Private, Branded Workspace with Reg API] 

=== What the Reg API Can Do ===
With the Reg API, you can:
* Register Second Life Residents from your website and track them.
* Provide customized and branded registration.
* Add newly registered Residents to a Second Life group.
* 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:
* Provide inventory, create attachments, or control the Resident's outfit
* Alter the appearance of the SL 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 Apply for Reg API ===
Before applying, please read the section "Important limitations and conditions apply" above. In general, we only approve requests that involve: limit to estate, custom name, or registration of an organization's members behind their login or firewall. Public registration should use [[SLURL#If_the_person_doesn.27t_have_Second_Life|DirectSLURL]].

To request participation in the beta Registration API program, submit the [[Linden Lab Official:Sign up to use the Registration API|Registration API Request Form]]. Linden Lab will contact you by email after reviewing your application.  If you have had a RegAPI account that was recently closed, reapply via the [https://spreadsheets.google.com/viewform?formkey=dDVoWm5vOUVqeDdaelEzc0twZFJpX3c6MA RegAPI Renewal Form].

=== Important Notices ===
{{KBcaution|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 [[Linden Lab Official:API Terms of Use|API Terms Of Use]].

=== Discussion and Support ===
* Use the [[Talk:Registration API|talk page]] to post questions about the RegAPI.
* 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]].

== How to Set Up Your Reg API ==
'''Setting up your Reg API'''
# Fill out and submit the [[Linden Lab Official:Sign up to use the Registration API|Registration API Request Form]]. Linden Lab will respond by email.
# Verify your capabilities using the [[Linden_Lab_Official:Sign_up_to_use_the_Registration_API#Check_your_capabilities| 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 [[Registration API Error Codes|error code]].
#* Create registrations to test the most common [[Registration API Error Codes|error codes]] and verify that you receive and properly handle them appropriately.

'''Testing Your Reg API'''
If you are using the Reg API to sign up registrants on the main grid, users under 13 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 for best results.

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|capabilities]] represent permissions to perform certain actions. The Reg API grants capabilities with ''capability URLs'' of the form:

{{Command|<nowiki>https://cap.secondlife.com/cap/0/</nowiki>''UUID''}}

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

For example:

{{Command|<nowiki>https://cap.secondlife.com/cap/0/2897456b-6959-473e-9b94-36d8cec1b9c3</nowiki>}}

The Reg API provides capability URLs for the following operations:
* '''add_to_group''' - add a new user to the specified Second Life group.
* '''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''' - return last names and corresponding IDs with which you are able to register new users. 
* '''get_error_codes''' - return the set of error codes.

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

For example, consider the [[Linden_Lab_Official:Sign_up_to_use_the_Registration_API#Check_your_capabilities|check capabilities form]].  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:

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

<tr><td>Last Name</td><td><input name='last_name'></td></tr>

<tr><td>Password</td><td><input name='password' type='password'></td></tr>
<tr><td>&nbsp;</td></tr>
<tr><td align='center' colspan=2><input type='submit' value="Get Capabilities"></td></tr>
</table>
</form></html4strict>

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

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

<xml><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></xml>

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

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.

''' 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:

<xml><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></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:

<ruby> 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</ruby>

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

== Troubleshooting ==
''' 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 [[Registration_API_Reference#create_user|create_user]] for details.  

To find your estate Code (as of March 16th 09):
# {{KeyCombo|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. 

''' Some Accounts Can't Access an 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, you must first add the the new users to the requisite group for them to be able to enter your estate.

Alternatively, you can subdivide your estate and create a parcel that has no restrictions, set your landing area there, then add new users to the group(s) to enable them to access the rest of the Estate.

'''Other Troubleshooting 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'rve including your capabilities URL and have properly set up your account and the location in the script
* Check for [[Registration API Error Codes | error codes]]

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

[[Category:RegAPI]]