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

From Second Life Wiki
Jump to navigation Jump to search
m
 
(41 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{multi-lang}}
{{multi-lang}}
{{:Web Services Portal/navigation}}
{{Supported API}}
{{:API Portal/navigation|reg}}
__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]].


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:
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.
* Create, manage, and track your community in Second Life.
* Maintain your brand identity from your website through user registration and into Second Life.
<br>
== 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 [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]].


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


The Reg API is a simple [http://en.wikipedia.org/wiki/REST#RESTful_Web_services 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]].
===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.


=== What the Reg API can do ===
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:
With the Reg API, you can:
* Register Second Life Residents from your website and track them.
* Register Second Life Residents from your website and track them.
* Provide customized and branded registration.
* 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.
* Send them to a location of your choice when they first log in to Second Life.
* Limit accounts to your estate.
* 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.
* 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.
* Provide registrations for your organization with internal access only, for example using an internal web site.


=== What the Reg API cannot do ===
=== What the Reg API Cannot Do ===
The Reg API '''does not''' provide the ability to:
The Reg API '''does not''' provide the ability to:
* Assign new Residents to groups
* Provide inventory, create attachments, or control the Resident's outfit
* Provide inventory, create attachments, or control the Resident's outfit
* Alter the appearance of the Viewer.
* 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.
* 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 ===
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.
To request participation in the beta Registration API program, submit the [http://secondlife.com/solution_providers/api/reg_form.php Registration API Request Form]. Linden Lab will contact you by email after reviewing your application.


=== Important notices ===
=== How to Apply for Reg API ===
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.  
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]].


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.
To request participation in the beta Registration API program, submit the [[Linden Lab Official:Registration API Request Form|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].


All participants in the Reg API program must abide by Linden Lab's [http://secondlifegrid.net/programs/api/tos  API Terms Of Service].
=== 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 ===
=== Discussion and Support ===
* Use the [[Talk:Registration API|talk page]] to post questions about the RegAPI.
* Use the [[Talk:Registration API|talk page]] to post questions about the RegAPI.
* Use the [https://lists.secondlife.com/cgi-bin/mailman/listinfo/regapi 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]].
* 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 ==
== How to set up your Reg API ==
 
===Setting up your Reg API===
To use the 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.
# Fill out and submit the [http://secondlife.com/solution_providers/api/reg_form.php Registration API Request Form]. Linden Lab will respond by email.
# Verify your capabilities using the [[Linden Lab Official:Registration API Request Form#Check_your_capabilities| capabilities form]].
# Verify your capabilities using the [http://secondlife.com/developers/third_party_reg/#what_are_cap 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.
# 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
# Create your registration web page
# If using PHP, make sure the necessary libraries are installed and working (see http://uk.php.net/phpinfo )
# If using PHP, make sure the necessary libraries are installed and working (see http://uk.php.net/phpinfo)
# Test your registration application:
# Test your registration application:
#* Register several new users.
#* Register several new users.
Line 61: Line 69:
#* Create registrations to test the most common [[Registration API Error Codes|error codes]] and verify that you receive and properly handle them appropriately.
#* Create registrations to test the most common [[Registration API Error Codes|error codes]] and verify that you receive and properly handle them appropriately.


'''WHEN TESTING'''
===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.


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.


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.
===Using capability URLs===
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:
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|<nowiki>https://cap.secondlife.com/cap/0/</nowiki>''UUID''}}


Where ''UUID'' is the UUID (universally unique identifier) granted for the specific capability.
Where ''UUID'' is the UUID (universally unique identifier) granted for the specific capability.
Line 78: Line 84:
For example:
For example:


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


The Reg API provides capability URLs for the following operations:
The Reg API provides capability URLs for the following operations:
* '''create_user''' - create a new user
* '''add_to_group''' - add a new user to the specified Second Life group.
* '''check_name''' - indicates whether a user can be registered with a given Second Life first name and last name
* '''create_user''' - create a new user.
* '''get_last_names''' - returns last names and corresponding IDs with which you are able to register new users.  
* '''check_name''' - indicates whether a user can be registered with a given Second Life first name and last name.
* '''get_error_codes''' - returns the set of error codes
* '''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 more information on these operations, see the [[Registration API Reference]].


For example, consider the [https://www.secondlife.com/developers/third_party_reg/#what_are_cap example capabilities form] provided on the Second Life website.  It requests a description of the capabilities currently granted to you.  
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:
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>
<syntaxhighlight lang="html5">
<form action="https://cap.secondlife.com/get_reg_capabilities" method="POST"><br />
<form action="https://cap.secondlife.com/get_reg_capabilities" method="POST">
<table>
    <p><label>First Name <input name="first_name"></label></p>
<tr><td>First Name</td><td><input name='first_name'></td></tr>
    <p><label>Last Name <input name="last_name"></label></p>
 
    <p><label>Password <input name="password" type="password"></label></p>
<tr><td>Last Name</td><td><input name='last_name'></td></tr>
    <p><input type="submit" value="Get Capabilities"></p>
 
<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>
</form>
</pre>
</syntaxhighlight>


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


<pre>
<syntaxhighlight lang="xml">
<llsd>
<llsd>
   <map>
   <map>
Line 117: Line 117:
   </map>
   </map>
</llsd>
</llsd>
</pre>
</syntaxhighlight>


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


<pre>
<syntaxhighlight lang="xml">
<llsd>
<llsd>
   <map>
   <map>
Line 137: Line 137:
   </map>
   </map>
</llsd>
</llsd>
</pre>
</syntaxhighlight>


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


=== Using LLSD with the Reg API ===
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:
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>
<syntaxhighlight lang="xml">
  <map>
<llsd>
    <key>dob</key><string>1987-07-06</string>
  <map>
    <key>start_region_name</key><string>da boom</string>
    <key>dob</key><string>1987-07-06</string>
    <key>username</key><string>mistaht</string>
    <key>start_region_name</key><string>da boom</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>username</key><string>mistaht</string>
    <key>password</key><string>123456</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>email</key><string>ben@ben.com</string>
    <key>password</key><string>123456</string>
  </map>
    <key>email</key><string>ben@ben.com</string>
</llsd>
  </map>
</llsd>
</syntaxhighlight>


This document represents a map (hash) containing keys for:
This document represents a map (hash) containing keys for:
Line 170: Line 176:
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:
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'
<syntaxhighlight lang="ruby">
require 'LLSD'
   
   
native_obj = 123
native_obj = 123
llsd_xml = LLSD.to_xml(native_obj) # returns <llsd><integer>123</integer></llsd>
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
returned_native_obj = LLSD.parse(llsd_xml) # returns native ruby integer, 123</ruby>
</syntaxhighlight>


If you, however, are running into problems encoding and decoding LLSD XML, look at the actual LLSD XML being sent and received to start debugging.
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==
== Troubleshooting ==
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 detals.   
''' 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):
To find your estate Code (as of March 16th 09):
Line 187: Line 196:
# Look at the Region tab.  The Estate ID is listed there.  
# Look at the Region tab.  The Estate ID is listed there.  


=== Accounts can't access estate ===
''' 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, the new registrations won't be able to enter your 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.
 
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 ==
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.
* 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.
* 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 [http://secondlife.com/developers/third_party_reg/#what_are_cap What are Capability URLs]) and properly set up your account and the location in the script
* 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]]
* Check for [[Registration API Error Codes | error codes]]
* [https://lists.secondlife.com/cgi-bin/mailman/listinfo/regapi 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''':


'''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/
* 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]].
* Or if you like living dangerously, try [[RegAPI_for_PHP5]].
* Make sure the Curl library is installed and running.
* Make sure the Curl library is installed and running.


[[Category:RegAPI| RegAPI]]
[[Category:RegAPI]]

Latest revision as of 15:10, 3 October 2023

NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.


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 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 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 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 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 DirectSLURL is a preferable option.

For more information on the RegAPI see the Working Inworld blog post 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 DirectSLURL.

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. If you have had a RegAPI account that was recently closed, reapply via the RegAPI Renewal Form.

Important Notices

KBcaution.png Important: 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 Use.

Discussion and Support

How to set up your Reg API

Setting up your Reg API

  1. Fill out and submit the Registration API Request Form. Linden Lab will respond by email.
  2. Verify your capabilities using the capabilities form.
  3. 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.
  4. Create your registration web page
  5. If using PHP, make sure the necessary libraries are installed and working (see http://uk.php.net/phpinfo)
  6. 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.

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

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

<form action="https://cap.secondlife.com/get_reg_capabilities" method="POST">
    <p><label>First Name <input name="first_name"></label></p>
    <p><label>Last Name <input name="last_name"></label></p>
    <p><label>Password <input name="password" type="password"></label></p>
    <p><input type="submit" value="Get Capabilities"></p>
</form>

When you submit a form such as this, the Reg API returns an XML 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 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.

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:

<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 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</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 create_user for details.

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

  1. Ctrl-Alt-⇧ Shift-D to enable the extra pull-down advanced menu.
  2. Then use Advanced > View Admin Options (near the bottom).
  3. From new pull-down menu Admin, select God Tools.
  4. 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 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.