Domain management

Contents

Once a session is established the complete set of domain management commands can be issued from checking domain(s) availability, creating a domain, updating a domain’s objects, to even deleting a domain. EPP commands issued to the EPP Gateway are process in REAL-TIME and responded back to the client.

1. Check domain availability

<check> command provide possibility to check availability for single domain and/or for multiple domains.

EPP Gateway command request/response:

 

2. Create domain

The create command allows the creation of a domain name. During the domain creation process host object(s) (name servers) are also created if they do not exist in ST Registry hosts repository. If host object used in domain creation process already exist in hosts repository then it just linked with newly created domain. In case if there is a need to assign IP address(es) to the host (for DNS glue record) – this should be done with a separate <update> command request for corresponding host object. EPP Gateway request/response:

3. Domain name server handling

Name server hosts for domain delegation specified as references to existing host objects, which describe a host machine. If host object have IP address(es) (for DNS glue records) – they can be fetched only by querying corresponding host object using <info> command.

Name servers are specified within a <domain:ns> element. This element MUST contain one or more <domain:hostObj> elements. A <domain:hostObj> element contains the fully qualified name of a known name server host object.

Domain Host Object Example:

4. Query domain info

The EPP <info> command is used to retrieve information associated with a domain object.

EPP Gateway command request/response:

The EPP <info> command also provide possibility to query domain information OUTSIDE Registrar repository, in this case AuthCode for domain is required.

EPP Gateway command request:

Response format for such request is identical to EPP <info> command for domain(s) within Registrar repository.

5. Domain update

The EPP <update> command allows modification of attributes of a domain object. The <update> command MUST contain a <domain:update> element that identifies the domain. The <domain:update> element contains the following child elements:

  • A <domain:name> element that contains the fully qualified name of the domain object to be updated.
  • An OPTIONAL <domain:add> element that contains attribute values to be added to the object.
  • An OPTIONAL <domain:rem> element that contains attribute values to be removed from the object.
  • An OPTIONAL <domain:chg> element that contains object attribute values to be changed.

EPP Gateway command request:

Successful response message:

 

6. Delete domain

The <delete> command allows a client to delete a domain object. In addition to the standard EPP command elements, the <delete> command MUST contain a <domain:delete> element that identifies the domain.

Delete command doesn’t terminate domain immediately, instead, it put it to the deletion queue and assign status pendingDelete which mean that domain will be terminated within 5 days from a moment when this status was assigned, in other words this operation move domain to the termination state described on domain life cycle page

EPP Gateway command request/response:

7. Renew domain

The EPP Gateway <renew> command is used to extend the validity period of an existing domain. The elements needed to identify and extend the validity period of a domain include the current expiration date of the domain (<domain:curExpDate>) and the period to extend, which is measured in whole numbers and is of unit “y” for years or “m” for months. Refer to your billing plan to identify how you can use “m”/months unit. <domain:curExpDate> ensures that repeated <renew> commands do not result in multiple, unanticipated successful renewals.

EPP Gateway command request/response:

8. Domain transfer

The <transfer> command is used to manage changes in domain sponsorship of an existing domain. Registrars can “request”, “cancel”, “approve”, “reject”, or “query” a transfer request using the “op” command attribute.

A registrar who wishes to assume sponsorship of a known domain from another registrar uses the <transfer> command with the value of the “op” attribute set to “request” which initiate domain transfer process. Once a transfer has been requested, the same registrar can cancel the request using a <transfer> command with the value of the “op” attribute set to “cancel”. A request to cancel the transfer MUST be sent to the server before the loosing registrar either approves or rejects the transfer request and before the server automatically processes the request due to responding registrar inactivity. If loosing registrar will not respond to the transfer request within 7 days from a date when it was initiated ST Registry will automatically approve the transfer request.

Once a transfer request has been received by the Gateway, the server MUST notify the current domain sponsor of the requested transfer. Every event that occurs during transfer process create corresponding notification. More details about ST Registry notification system can be found on notifications page. The current status of a pending <transfer> command for any domain can be found using the <transfer> query command.

The current domain sponsor(loosing registrar) MAY explicitly approve or reject the transfer request. The client can approve the request using a <transfer> command with the value of the “op” attribute set to “approve”. Clients can reject the request using a <transfer> command with the value of the “op” attribute set to “reject”.

Authorization password (AuthCode/EPP Code) is required to complete a <transfer> command.

Domain transfer initiate domain renewal when transfer request is completed. Renewal period is provided in <transfer> command with the value of the “op” attribute set to “request”. Minimum renewal period is defined in registrar billing plan. If ST Registry will be unable to complete successfully domain renewal (for example due to insufficient funds on registrar account) – transfer will be rejected and will gain status “serverRejected”.

<transfer> command – Request

EPP command <transfer op=”request”> initiate domain transfer to another registrar. To send command <transfer op=”request”> gaining registrar should provide domain password (AuthInfo, also known as AuthCode/EPPCode). If domain have status clientTransferProhibited, serverTransferProhibited or pendingTransfer command <transfer op=”request”> will be rejected.

After successful <transfer op=”request”> command – domain will gain status “pendingTransfer” (more about statuses can be found on page “Domain statuses“), together with this ST Registry will send transfer request notification to the loosing registrar (read more about notifications on page “Registrar notifications“). Loosing registrar will have 7 days to process transfer request (accept or decline it). Gaining registrar is able to check transfer status by querying EPP command <transfer op=”query”>.

If loosing registrar doesn’t handle transfer request within 7 days after domain transfer request was initiated – such request will be automatically approved by ST Registry:

  • Transfer is automatically approved and gain status “serverApproved”.
  • Domain with all assiciated hosts transferred to the gaining registrar.
  • Created clone for all domain contacts (registrant, admin, billing and technical) in gaining registrar repository.
  • pendingTransfer status removed from domain.
  • Domain gain serverTransferProhibited status for 60 days.
  • Domain renewed for the period provided in transfer request.
  • AuthInfo reset (AuthCode/EPPCode). ST Registry will generate new AuthCode which can be retrieved by new registrar with “Query domain info command“.

Command <transfer op=”request”> contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:period unit=”y”> or <domain:period unit=”m”> – renewal period which should be applied after transfer approval. Unit “m” (months) depends from billing attribute called “Billing period”.
  • <domain:authInfo> – element which define AuthInfo for domain (also known as AuthCode or EPPCode).

 

After successful <transfer op=”request”> command execution response will contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:trStatus> – Current status for transfer operation – “pending”
  • <domain:reID> – gaining registrar identifier who have created transfer request.
  • <domain:reDate> – date and time when transfer request was initially performed.
  • <domain:acID> – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
  • <domain:acDate> – date and time when corresponding request was handled.
  • <domain:exDate> – domain expiration date on the date <domain:reDate>.

<transfer> command – Cancel

EPP command <transfer op=”cancel”> is supposed to be used to cancel previously created transfer request.

<transfer op=”cancel”> is accepted only from a registrar who have previously initiated transfer request and only if transfer process was not finished (domain is still in status pendingTransfer).

After successful command execution:

  • transfer request application is cancelled and application status is updated to “clientCancelled”.
  • pendingTransfer” status is removed from corresponding domain.

<transfer op=”cancel”> command contain element:

  • <domain:name> – fully identified domain name.

After successful <transfer op=”cancel”> command execution response will contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:trStatus> – Current status for transfer operation – “clientCancelled”
  • <domain:reID> – gaining registrar identifier who have created transfer request.
  • <domain:reDate> – date and time when transfer request was initially performed.
  • <domain:acID> – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
  • <domain:acDate> – date and time when corresponding request was handled.
  • <domain:exDate> – domain expiration date on the date <domain:reDate>.

<transfer> command – Approve

EPP command <transfer op=”approve”> should be used to approve/accept currently active (status pending) transfer request(s). To be able to successfully submit <transfer op=”approve”> registrar should ensure that domain is currently in pendingTransfer state (how to check read “QUERY” command.

After successful command execution:

  • Transfer application is approved and gain status “clientApproved”
  • Domain and related hosts are transferred to the new registrar
  • pendingTransfer status from removed from domain and all related objects
  • Domain renewed for the period provided in transfer request.
  • AuthInfo reset (AuthCode/EPPCode). ST Registry will generate new AuthCode which can be retrieved by new registrar with “Query domain info command”.

After successful <transfer op=”cancel”> command execution response will contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:trStatus> – Current status for transfer operation – “clientApproved”
  • <domain:reID> – gaining registrar identifier who have created transfer request.
  • <domain:reDate> – date and time when transfer request was initially performed.
  • <domain:acID> – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
  • <domain:acDate> – date and time when corresponding request was handled.
  • <domain:exDate> – domain expiration date on the date <domain:reDate>.

<transfer> command – Reject

EPP command <transfer op=”reject”> should be used to reject currently active (status pending) transfer request(s). To be able to successfully submit <transfer op=”reject”> registrar should ensure that domain is currently in pendingTransfer state (how to check read “QUERY” command.

After successful command execution:

  • Transfer request application is rejected and gain status “clientRejected” (which mean transfer rejected by current/loosing registrar).
  • pendingTransfer status is removed from domain.

<transfer op=”reject”> command contain element:

  • <domain:name> – fully identified domain name.

After successful <transfer op=”cancel”> command execution response will contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:trStatus> – Current status for transfer operation – “clientRejected”
  • <domain:reID> – gaining registrar identifier who have created transfer request.
  • <domain:reDate> – date and time when transfer request was initially performed.
  • <domain:acID> – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
  • <domain:acDate> – date and time when corresponding request was handled.
  • <domain:exDate> – domain expiration date on the date <domain:reDate>.

<transfer> command – Query

EPP command <transfer op=”query”> is supposed to be used to identify transfer operation state for domain to another registrar. This command doesn’t perform any updates to the object.

With command <transfer op=”query”> it is possible to track execution of latest transfer request operation (see <domain op=”request”>). This command is available for both – requesting and loosing registrar. This information might be accessed by providing AuthInfo in <transfer op=”query”> request.

To request <transfer op=”query”> command, registrar who is not currently identified as a domain registrar should provide AuthInfo in <transfer op=”query”> request. Current domain registrar is able to request <transfer op=”query”> command without providing AuthInfo.

<transfer op=”query”> request contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:authInfo> – optional(read above) element which define AuthInfo for domain (also known as AuthCode or EPPCode).

 

After successful <transfer op=”query”> command execution response will contain following elements:

  • <domain:name> – fully identified domain name.
  • <domain:trStatus> – Current status for transfer operation which might be:
    • pending – operation is not completed. This is normally default state.
    • clientApproved – transfer was confirmed by the loosing registrar.
    • clientRejected – transfer was rejected by the loosing registrar.
    • clientCancelled – transfer request was cancelled by gaining registrar.
    • serverApproved – transfer was completed by ST Registry. This will happen after loosing registrar inactivity for more than 7 days.
    • serverCancelled – transfer was rejected by ST Registry.
  • <domain:reID> – gaining registrar identifier who have created transfer request.
  • <domain:reDate> – date and time when transfer request was initially performed.
  • <domain:acID> – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
  • <domain:acDate> – date and time when corresponding request was handled.
  • <domain:exDate> – domain expiration date on the date <domain:reDate>.

 

 

9. Auth Info/EPP Code requirements

When registrar create or update domain and define Auth Info/EPP Code (later EPP Code) for domain on his side – there is a strict rule for it and defined value should pass through validation process to ensure that it meet requirements on ST Registry side:

  • Minimum length 6 symbols
  • Maximum length 16 symbols
  • Code should include at least 1 uppercase character
  • Code should include at least 1  lowercase character
  • Code should include at least one digit
  • If Auth Info/EPP Code contain XML illegal characters (&, < and >) then it should be placed in CDATA container.

If provided EPP code will not meet requirements above – such EPP request will generate error.

 

10. Response codes

To simplify initial integration process, instead of general error messages, ST Registry provide different response messages for same response code depending from exception which generated corresponding response code. Below you can find list of all possible response codes and their messages for domain related operations.

Response code Message
1000 Command completed successfully
2002 Name server duplicate. NS host name should be unique within same domain.
2002 Specified expiration date and real expiration date mismatch
2003 Missing domain name
2003 registrant, admin, tech and billing contacts are required to complete operation
2003 Missing renewal params
2004 domain:period minLength value=1, maxLength value=99
2004 domain:period unit m|y
2004 pw minLength value=’6′, maxLength value=’16’
2005 Invalid domain:name
2005 Domain is not within allowed list of zones. Allowed zones: st
2005 pendingDelete status MUST NOT be combined with either clientDeleteProhibited or serverDeleteProhibited status and MUST NOT be combined with enother pending statuses.
2005 pendingRenew status MUST NOT be combined with either clientRenewProhibited or serverRenewProhibited status and MUST NOT be combined with enother pending statuses.
2005 pendingTransfer status MUST NOT be combined with either clientTransferProhibited or serverTransferProhibited status and MUST NOT be combined with enother pending statuses.
2005 pendingUpdate status MUST NOT be combined with either clientUpdateProhibited or serverUpdateProhibited status and MUST NOT be combined with enother pending statuses.
2005 Password should have both upper and lower case characters
2005 Password should contain one or more numbers
2005 Unknown transfer operation
2104 Client billing state is locked. Further billing operation(s) disallowed. Contact Registry support for clarifications
2104 Not enough funds on registrar balance to complete operation
2106 Object is not eligible for transfer
2201 Operation not permitted
2201 Auth code update disallowed during domain pending transfer
2201 Transfer was initiated by another registrar
2203 Operation not permitted; Domain object not in client repository
2300 Domain {domain} already in pending transfer state
2301 {domain} is not in pending transfer state
2302 Domain name already exists
2303 Contact {id} does not exists
2304 Object status prohibits operation
2304 domain is in pending transfer state
2304 domain is already in pending delete state
2304 Domain already in redemption period

dotster