Autenticação

Muitas (mas não todas) das operações disponibilizadas na API do UOL Cloud Storage necessitam de autenticação prévia para poderem ser realizadas, em especial aquelas que criam, excluem ou alteram arquivos e configurações do UOL Cloud Storage. Para realizar essa autenticação, uma invocação à API REST do UOL Cloud Storage deve ser realizada por meio de uma requisição HTTPS do tipo GET com o caminho https://api.uolos.com.br/auth/v1.0, tal como demonstrado no exemplo abaixo:

1. Requisição HTTP para a realização da autenticação:

GET https://api.uolos.com.br/auth/v1.0 HTTP/1.1
X-Auth-User: 123abc456:uol
X-Auth-Key: xYz890BcD765gHi321

Tal como demonstrado no exemplo, a URL de destino da requisição deve ser https://api.uolos.com.br/auth/v1.0 para o autenticação, além dos cabeçalhos HTTP: X-Auth-User e X-Auth-Key com valores para a chave de acesso (ou Acces Key que terá sempre o sufixo :uol) e a respectiva senha (Secret Key). O valor da chave de acesso e da senha podem ser visualizados na tela de gerenciamento do UOL Cloud Storage. Caso seja necessário, a senha também poderá ser alterada nesta mesma tela.

Alternativamente, para manter compatibilidade com alguns programas clientes, os cabeçalhos HTTP X-Storage-User e X-Storage-Pass podem ser usados em lugar dos cabeçalhos X-Auth-User e X-Auth-Key.

GET https://api.uolos.com.br/auth/v1.0 HTTP/1.1
X-Storage-User: 123abc456:uol
X-Storage-Pass: xYz890BcD765gHi321

Após a realização da chamada HTTPS da requisição, uma resposta será recebida tal como no exemplo abaixo:

2. Resposta HTTPS para a realização da autenticação:

HTTP/1.1 200 OK
Date: Sun, 01 Set 2013 15:32:21 GMT
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Connection: keep-alive
Server: UOLOS-1.0.6
X-Storage-Url: https://api.uolos.com.br/v1/UOL_123abc456
X-Auth-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987
X-Storage-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987

Tal como demonstrado no exemplo, quando a autenticação é feita com sucesso, um status HTTP 200 é retornado e a resposta conterá os cabeçalhos X-Storage-Url, X-Auth-Token e X-Storage-Token. Qualquer resposta com status 2xx é uma resposta que indica o sucesso da requisição. Um status HTTP 401 é devolvido se a senha estiver incorreta. Um status HTTP 400 é devolvido se a chave de acesso estiver incorreta, mal-formada ou inativa.

Após a etapa de autenticação ser realizada com sucesso, todas as invocações subsequentes devem ser realizadas para a URL e caminhos especificada no cabeçalho X-Storage-Url e devem incluir o cabeçalho X-Auth-Token na requisição com o valor informado na resposta da autenticação. Para manter a compatibilidade com alguns programas clientes, o cabeçalho X-Storage-Token também pode ser utilizado em lugar do cabeçalho X-Auth-Token.

As operações posteriores à etapa de autenticação seriam enviadas para o caminho /v1/UOL_123abc456, da URL api.uolos.com.br, por meio de HTTP. No UOL Cloud Storage o valor do cabeçalho X-Storage-Url sempre será https://api.uolos.com.br/v1/UOL_123abc456. Além disso, cada requisição posterior deverá também enviar o cabeçalho X-Auth-Token (ou alternativamente X-Storage-Token) com o valor informado no cabeçalho X-Auth-Token da resposta da autenticação. É importante observar-se que esse token de autenticação é válido por um período de 24 horas.

Veja, a seguir, alguns exemplos de requisições.

3. Exemplo de uma requisição autenticada para baixar um arquivo:

GET https://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1
X-Auth-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987

Neste exemplo, nota-se que a parte do caminho https://api.uolos.com.br/v1/UOL_123abc456 utilizado na requisição autenticada é extraído do cabeçalho X-Storage-Url. Nota-se também que o cabeçalho X-Auth-Token informado na requisição tem o mesmo valor da resposta do cabeçalho X-Auth-Token recebido na resposta da autenticação.

Caso o container, ou pasta, onde o arquivo se encontra for configurada como público (ver documentação "container público") não e necessário informar o cabeçalho X-Auth-Token, e o protocolo HTTPS é opcional.

GET http://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1

ou

GET https://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1