Criar ou atualizar um segredo de API
  • 6 minutos de leitura
  • Tema escuro
    Tema claro
  • Pdf

Criar ou atualizar um segredo de API

  • Tema escuro
    Tema claro
  • Pdf

Resumo do artigo

Este artigo apresenta como criar ou atualizar um segredo de API no MySafe via API, os endpoints disponíveis, os parâmetros necessários, exemplos de requisições e respostas em caso de sucesso ou em caso de erros.

Autorização

A autorização para as APIs MySafe é feita diretamente no módulo.
Para mais informações, acesse o documento sobre Como adicionar uma autorização de chave de acesso.

Autenticação

A autenticação nas APIs MySafe é feita utilizando o método de autenticação OAuth 2.0. Para iniciar este processo, é necessário fornecer o Client ID e o Client Secret, além de obter o token de autenticação deles a partir do endpoint:

GET /api/oauth2/token

Para mais informações sobre como obter o Client ID e o Client Secret, acesse o documento sobre Como visualizar uma autorização de chave de acesso.

Métodos

Criar um segredo de API

Requisição

Para adicionar um segredo de API ao MySafe, envie uma requisição para o seguinte endpoint:

POST /api/mysafe/secretapi
Info

Quando um segredo de API é adicionado ao MySafe, ele é automaticamente associado ao seu criador, identificando-o como seu proprietário.

Parâmetros de requisição

Body

CampoTipoObrigatórioDescriçãoExemplo
nameStringSimNome atribuído ao segredo de API.gcp
urlStringSimURL do site onde o segredo de API está sendo usado.https://gcp.com
client_idStringSimID da aplicação cliente que usará este segredo da API.gf455f7g8fb5dfg8fd545bffbv
client_secretStringSimUma chave confidencial conhecida apenas pelo cliente e pelo servidor de autorização, usada para autenticar o cliente junto ao servidor.gf5464g5v7ffsd857xc4fds57g8fds
identifier_codeStringNãoString única definida pelo usuário para identificar o segredo de API.hyga125
tagsStringNãoPalavras-chave para ajudar a identificar o segredo de API.Cloud
notesStringNãoObservações sobre o segredo da API.Access details
methodStringNãoO método HTTP a ser usado para as requisições da API.get
users_allowedArray de objetosNãoInformação sobre os usuários com permissão de acesso ao segredo de API.
usernameStringNãoNome de usuário do usuários que poderá acessar o segredo da API.pduarte
can_editBooleanNãoPermissão de edição. Se deixado vazio, o usuário terá apenas permissão de visualização.true
groups_allowedArray de objetosNãoInformação sobre os grupos com permissão de acesso ao segredo de API.
nameStringNãoNome do grupo com permissão de acesso ao segredo de API.Test group
can_editBooleanNãoPermissão de edição. Se deixado vazio, o usuário terá apenas permissão de visualização.

Exemplo de requisição

{
    "name": "GCP",
    "url": "https://gcp.com",
    "client_id": "gf455f7g8fb5dfg8fd545bffbv",
    "client_secret": "gf5464g5v7ffsd857xc4fds57g8fds",
    "identifier_code": "hyga125",
    "tags": "Cloud",
    "notes": "Access details",
    "method": "get",
     "users_allowed": [
        {
            "username" : "pduarte",
            "can_edit" : true
        }
    ],
    "groups_allowed": [
        {
            "name" : "Test group"
        }
    ]
}

Retorno

Adiciona um segredo de API ao MySafe, e retorna uma mensagem com informações sobre o processo de adição do segredo de API.

Resposta esperada

HTTP/1.1 201 Created
{
    "code": 201,
    "response": {
        "status": 201,
        "message": "Api secret successfully registered",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Api secret successfully registered",
        "erro": false,
        "cod_erro": 0
    },
    "api_entity": {
        "identifier": "43",
        "name": "GCP",
        "url": "https://gcp.com",
        "client_secret": "gf5464g5v7ffsd857xc4fds57g8fds",
        "client_id": "gf455f7g8fb5dfg8fd545bffbv",
        "identifier_code": "hyga125",
        "method": "get",
        "tags": "Cloud",
        "notes": "Access details",
        "users_allowed": [
            {
                "username": "pduarte",
                "can_edit": true
            }
        ],
        "groups_allowed": [
            {
                "name": "Test group",
                "can_edit": false
            }
        ],
        "shared_error": []
    }
}

Em caso de erro - parâmetro obrigatório ausente

HTTP/1.1 400 Bad Request
{
    "code": 400,
    "response": {
        "status": 400,
        "message": "1001: Parameter 'name' was not informed!",
        "error": true,
        "error_code": 1,
        "detail": "",
        "mensagem": "1001: Parameter 'name' was not informed!",
        "erro": true,
        "cod_erro": 1
    },
    "exception": {
        "code": 1001,
        "message": "1001: Parameter 'name' was not informed!",
        "detail": null
    }
}

Atualizar um segredo de API

Requisição

Para atualizar um segredo de API no MySafe, envie uma requisição para o seguinte endpoint:

PUT /api/mysafe/secretapi/update/[identifier]

Parâmetros de requisição

Path

CampoTipoObrigatórioDescriçãoExemplo
identifierstringSimCódigo identificador único associado à cada entrada na tabela de segredos de API. Esse valor é automaticamente atribuído pelo senhasegura no momento de criação do segredo de API I e é obtido na resposta da requisição Listar todos os segredos de API ou Listar um segredo de API. Nota: não confunda com o parâmetro identifier_code, que é criado pelo usuário no momento de criação do segredo de API.43

Body

Info

Ao enviar uma requisição de atualização, não é necessário incluir parâmetros que você não deseja editar.

CampoTipoObrigatórioDescriçãoExemplo
nameStringNãoNome atribuído ao segredo de API.GCP1
urlStringNãoURL do site onde o segredo de API está sendo usado.https://gcp1.com
client_idStringNãoID da aplicação cliente que usará este segredo da API.hy7464g5v8ghy4d858jk7fds57t4tr
client_secretStringNãoUma chave confidencial conhecida apenas pelo cliente e pelo servidor de autorização, usada para autenticar o cliente junto ao servidor.hb455f7g8fg9dfg8yt845bxxku
identifier_codeStringNãoString única definida pelo usuário para identificar o segredo de API.gcp7852
tagsStringNãoPalavras-chave para ajudar a identificar o segredo de API.Cloud1
notesStringNãoObservações sobre o segredo da API.Access details for this API secret
methodStringNãoO método HTTP a ser usado para as requisições da API.get
users_allowedArray de objetosNãoInformação sobre os usuários com permissão de acesso ao segredo de API.
usernameStringNãoNome de usuário do usuários que poderá acessar o segredo da API.alices
can_editBooleanNãoPermissão de edição. Se deixado vazio, o usuário terá apenas permissão de visualização.true
groups_allowedArray de objetosNãoInformação sobre os grupos com permissão de acesso ao segredo de API.
nameStringNãoNome do grupo com permissão de acesso ao segredo de API.
can_editBooleanNãoPermissão de edição. Se deixado vazio, o usuário terá apenas permissão de visualização.

Exemplo de requisição

{
    "name": "GCP1",
    "url": "https://gcp1.com",
    "client_id": "hb455f7g8fg9dfg8yt845bxxku",
    "client_secret": "hy7464g5v8ghy4d858jk7fds57t4tr",
    "identifier_code": "gcp7852",
    "tags": "Cloud1",
    "notes": "Access details for this API secret",
     "users_allowed": [
        {
            "username" : "alices",
            "can_edit" : true
        }
    ],
    "groups_allowed": []
Info

Como o parâmetro method não foi editado, ele não foi incluído na requisição exemplificada acima.

Retorno

Atualiza um segredo de API armazenado no MySafe baseado em seu identifier e retorna uma mensagem com informações sobre o processo de atualização.

Resposta esperada

HTTP/1.1 200 OK
{
    "code": 200,
    "response": {
        "status": 200,
        "message": "Api secret updated successfully",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Api secret updated successfully",
        "erro": false,
        "cod_erro": 0
    },
    "api_entity": {
        "identifier": "43",
        "name": "GCP1",
        "url": "https://gcp1.com",
        "client_secret": "hy7464g5v8ghy4d858jk7fds57t4tr",
        "client_id": "hb455f7g8fg9dfg8yt845bxxku",
        "identifier_code": "gcp7852",
        "method": "get",
        "tags": "Cloud1",
        "notes": "Access details for this API secret",
        "users_allowed": [
            {
                "username": "alices",
                "can_edit": true
            }
        ],
        "groups_allowed": [],
        "shared_error": []
    }
}

Em caso de erro - identifier já encontrado em outro segredo de API deste usuário

HTTP/1.1 400 Bad Request
{
    "code": 400,
    "response": {
        "status": 400,
        "message": "1001: 'Identifier' already found in another API key of this user",
        "error": true,
        "error_code": 1,
        "detail": "",
        "mensagem": "1001: 'Identifier' already found in another API key of this user",
        "erro": true,
        "cod_erro": 1
    },
    "exception": {
        "code": 1001,
        "message": "1001: 'Identifier' already found in another API key of this user",
        "detail": null
    }
}

Em caso de erro - usuário não possui acesso a este segredo de API

HTTP/1.1 400 Bad Request
{
    "code": 400,
    "response": {
        "status": 400,
        "message": "1006: User does not have access",
        "error": true,
        "error_code": 1,
        "detail": "",
        "mensagem": "1006: User does not have access",
        "erro": true,
        "cod_erro": 1
    },
    "exception": {
        "code": 1006,
        "message": "1006: User does not have access",
        "detail": null
    }
}

Este artigo foi útil?